SimTX API v24/Account service - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:13:29Z

Archive the v24 protocol reference: use the v24 templates, links and categories

Clanker: Clanker moved page SimTX API/Account service to SimTX API v24/Account service: Archive the v24 protocol reference

2026-10-24T16:11:45Z

Clanker moved page SimTX API/Account service to SimTX API v24/Account service: Archive the v24 protocol reference

← Older revision	Revision as of 16:11, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:54:52Z

SimTX API documentation

New page

{{SimTX API navigation}}
The '''SimTX account service''' is the HTTPS JSON API at <code><nowiki>https://auth.simtx.net</nowiki></code>. It signs users in, issues credentials, lists the game servers that are online, and exchanges a credential for the single-use '''game ticket''' that a game server accepts during the [[SimTX API/Connection and handshake|handshake]]. It also serves a small set of public, unauthenticated endpoints.

A client that only '''receives''' does not need the account service at all, apart from discovering a server address. A client that '''transmits''' or publishes to the [[SimTX API/Extension catalog protocol|extension catalog]] does.

== Endpoint summary ==
{| class="wikitable"
! Method !! Path !! Authentication !! Purpose
|-
| <code>POST</code> || <code>/api/v1/device/authorizations</code> || None || [[SimTX API/Device login#Starting a login|Start a device login]]
|-
| <code>POST</code> || <code>/api/v1/device/token</code> || None || [[SimTX API/Device login#Polling for credentials|Poll for credentials]]
|-
| <code>POST</code> || <code>/api/v1/device/refresh</code> || None || [[SimTX API/Device login#Refreshing|Rotate the credential pair]]
|-
| <code>GET</code> || <code>/api/v1/servers</code> || Bearer || [[SimTX API/Server directory|List online game servers]]
|-
| <code>POST</code> || <code>/api/v1/game-tickets</code> || Bearer || [[SimTX API/Game tickets|Obtain a game ticket]]
|-
| <code>GET</code> || <code>/api/v1/status</code> || None || [[SimTX API/Public endpoints#Service status|Service status]]
|-
| <code>GET</code> || <code>/api/v1/profiles</code> || None || [[SimTX API/Public endpoints#Profile search|Search public profiles]]
|-
| <code>GET</code> || <code>/api/v1/profiles/{handle}</code> || None || [[SimTX API/Public endpoints#Single profile|Read one public profile]]
|-
| <code>GET</code> || <code>/api/v1/releases</code> || None || [[SimTX API/Public endpoints#Releases|Published transmitter releases]]
|-
| <code>GET</code> || <code>/downloads/transmitter-update.properties</code> || None || [[SimTX API/Public endpoints#Update manifest|Update manifest]]
|-
| <code>GET</code> || <code>/downloads/{filename}</code> || None || [[SimTX API/Public endpoints#Release downloads|Release download]]
|-
| <code>GET</code> || <code>/api/v1/network-test/ping</code> || None || [[SimTX API/Public endpoints#Network test|Latency probe]]
|-
| <code>POST</code> || <code>/api/v1/network-test/upload</code> || None || [[SimTX API/Public endpoints#Network test|Upload probe]]
|}

Endpoints under <code>/api/v1/me/</code>, <code>/api/v1/auth/</code> and the device approval endpoints (<code>/api/v1/device/verify</code>, <code>/api/v1/device/deny</code>, <code>GET /api/v1/device/authorizations/{userCode}</code>) belong to the account website. They require a browser session cookie and a CSRF token and do not accept bearer credentials. Administrative and internal endpoints are not part of the public API and are not documented here.

== Conventions ==
* '''Transport.''' HTTPS only. Request and response bodies are <code>application/json</code> (UTF-8) unless stated otherwise. Timestamps are ISO-8601 strings in UTC, for example <code>2026-10-24T12:00:00Z</code>.
* '''Field names''' are camelCase. Unknown response fields may be added in future and must be ignored by clients.
* '''Caching.''' Every <code>/api/</code> response carries <code>Cache-Control: no-store</code>.
* '''Timeouts.''' The official client uses a 5 second connect timeout and a 10 second request timeout. Those values are a sensible default.
* '''Request IDs.''' A client may send an <code>X-Request-ID</code> header matching <code>[A-Za-z0-9._-]{8,64}</code>. The service echoes it in the response header and in error bodies. Without one, the service generates a UUID. Quote it when reporting a problem.

== Authentication ==
Authenticated endpoints read a bearer credential from the <code>Authorization</code> header. The header must begin with exactly <code>Bearer </code> (capital B, one space).

<syntaxhighlight lang="http">
GET /api/v1/servers HTTP/1.1
Host: auth.simtx.net
Authorization: Bearer stx_at1_0f3c…
</syntaxhighlight>

Two kinds of credential are accepted as a bearer:
* an '''access credential''' obtained through [[SimTX API/Device login|device login]], or
* a '''personal credential''' created by the user on the account website. It is intended for bots, scripts and other headless software. The user chooses its scopes and expiry, and the secret is displayed once.

=== Credential formats ===
All SimTX credentials are opaque strings: a fixed prefix followed by 64 lowercase hexadecimal characters (32 random bytes). They are not JWTs and contain no readable data. A client must store them as given and must never parse them.

{| class="wikitable"
! Prefix !! Credential !! Lifetime !! Used for
|-
| <code>stx_dc1_</code> || Device code || 10 minutes || Polling <code>/api/v1/device/token</code>
|-
| <code>stx_at1_</code> || Access credential || 10 minutes || Bearer for authenticated endpoints
|-
| <code>stx_rt1_</code> || Refresh credential || 30 days idle, 180 days absolute; rotates on every use || <code>/api/v1/device/refresh</code>
|-
| <code>stx_pc1_</code> || Personal credential || Chosen by the user, at most 1 year || Bearer for authenticated endpoints
|-
| <code>stx_gt1_</code> || Game ticket || 60 seconds, single use || The game server [[SimTX API/Packets/Handshake|handshake]]
|}

A user code (shown to the person signing in) has the form <code>ABCD-EF23</code>: eight characters from the alphabet <code>ABCDEFGHJKLMNPQRSTUVWXYZ23456789</code>, with a hyphen after the fourth. The alphabet omits <code>I</code>, <code>O</code>, <code>0</code> and <code>1</code>, so nobody has to wonder which one they are looking at.

=== Storing credentials ===
* Keep the access credential in memory only. It expires after ten minutes in any case.
* Persist the refresh credential (or a personal credential) in the operating system's credential store, such as Keychain, Windows Credential Manager or Secret Service.
* There is no client-side logout endpoint. Signing out means deleting the stored refresh credential. Users revoke devices and personal credentials on the account website.
* Never send an access, refresh or personal credential to a game server. Game servers only ever see [[SimTX API/Game tickets|game tickets]].

== Errors ==
Every error response has the same JSON body:

<syntaxhighlight lang="json">
{
"code": "credential_invalid",
"message": "The access credential is invalid or expired",
"fieldErrors": {},
"requestId": "3d7f0c1e-5b2a-4a8e-9a77-1f0f6f5d2b10"
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>code</code> || string || Stable, machine-readable error code. Branch on this.
|-
| <code>message</code> || string || Human-readable English text. May change; do not parse.
|-
| <code>fieldErrors</code> || object || Additional string values keyed by name. For example, device polling reports the required poll interval as <code>fieldErrors.interval</code>.
|-
| <code>requestId</code> || string || The request ID. See [[#Conventions|Conventions]].
|}

=== Common error codes ===
{| class="wikitable"
! HTTP !! <code>code</code> !! Meaning
|-
| 401 || <code>credential_missing</code> || No <code>Authorization</code> header, or it does not start with <code>Bearer </code>.
|-
| 401 || <code>credential_invalid</code> || The bearer credential is unknown, expired, revoked, or belongs to an account that is not active. Refresh once and retry; if that fails, sign in again.
|-
| 400 || <code>scope_invalid</code> || A requested scope is not a known [[SimTX API/Permissions|permission]].
|-
| 400 || <code>ticket_request_invalid</code> || See [[SimTX API/Game tickets#Errors|Game tickets]].
|-
| 400 || <code>authorization_pending</code>, <code>slow_down</code>, <code>expired_token</code>, <code>access_denied</code>, <code>invalid_grant</code> || Device polling states. See [[SimTX API/Device login#Polling for credentials|Device login]].
|-
| 401 || <code>invalid_grant</code>, <code>refresh_reuse_detected</code> || Refresh failures. See [[SimTX API/Device login#Refreshing|Device login]].
|-
| 404 || <code>profile_not_found</code>, <code>release_artifact_not_found</code>, <code>release_manifest_unavailable</code> || The requested public resource does not exist.
|-
| 429 || <code>rate_limited</code> || A rate-limit bucket is exhausted. See below.
|-
| 500 || <code>internal_error</code> || Unexpected server failure. Retry later with backoff.
|}

== Rate limits ==
Rate limits are counted per client IP address, per bucket, in fixed one-minute windows aligned to the UTC minute. A request over the limit receives <code>429</code> with code <code>rate_limited</code>. No <code>Retry-After</code> header is sent, so wait for the next minute boundary.

{| class="wikitable"
! Bucket !! Endpoint(s) !! Requests per minute
|-
| <code>device-create</code> || <code>POST /api/v1/device/authorizations</code> || 20
|-
| <code>device-poll</code> || <code>POST /api/v1/device/token</code> || 120
|-
| <code>device-refresh</code> || <code>POST /api/v1/device/refresh</code> || 120
|-
| <code>server-directory</code> || <code>GET /api/v1/servers</code> || 120
|-
| <code>game-ticket</code> || <code>POST /api/v1/game-tickets</code> || 120
|-
| <code>public-directory</code> || <code>GET /api/v1/profiles</code> || 60
|-
| <code>public-profile</code> || <code>GET /api/v1/profiles/{handle}</code> || 120
|-
| <code>public-releases</code> || <code>GET /api/v1/releases</code> || 120
|-
| <code>release-manifest</code> || <code>GET /downloads/transmitter-update.properties</code> || 240
|-
| <code>release-download</code> || <code>GET /downloads/{filename}</code> || 240
|-
| <code>network-test-ping</code> || <code>GET /api/v1/network-test/ping</code> || 60
|-
| <code>network-test-upload</code> || <code>POST /api/v1/network-test/upload</code> || 144
|}

<code>GET /api/v1/status</code> is not rate limited.

== See also ==
* [[SimTX API/Device login]]: the sign-in flow for desktop and command-line software.
* [[SimTX API/Game tickets]]: how a credential becomes a game server connection.
* [[SimTX API/Permissions]]: scopes and numeric capabilities.

{{SimTX API navbox}}
[[Category:SimTX API]]
[[Category:SimTX API account service]]

← Older revision		Revision as of 16:13, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	The '''SimTX account service''' is the HTTPS JSON API at <code><nowiki>https://auth.simtx.net</nowiki></code>. It signs users in, issues credentials, lists the game servers that are online, and exchanges a credential for the single-use '''game ticket''' that a game server accepts during the [[SimTX API/Connection and handshake\|handshake]]. It also serves a small set of public, unauthenticated endpoints.		The '''SimTX account service''' is the HTTPS JSON API at <code><nowiki>https://auth.simtx.net</nowiki></code>. It signs users in, issues credentials, lists the game servers that are online, and exchanges a credential for the single-use '''game ticket''' that a game server accepts during the [[SimTX API v24/Connection and handshake\|handshake]]. It also serves a small set of public, unauthenticated endpoints.

	A client that only '''receives''' does not need the account service at all, apart from discovering a server address. A client that '''transmits''' or publishes to the [[SimTX API/Extension catalog protocol\|extension catalog]] does.		A client that only '''receives''' does not need the account service at all, apart from discovering a server address. A client that '''transmits''' or publishes to the [[SimTX API v24/Extension catalog protocol\|extension catalog]] does.

	== Endpoint summary ==		== Endpoint summary ==
Line 8:		Line 8:
	! Method !! Path !! Authentication !! Purpose		! Method !! Path !! Authentication !! Purpose
	\|-		\|-
	\| <code>POST</code> \|\| <code>/api/v1/device/authorizations</code> \|\| None \|\| [[SimTX API/Device login#Starting a login\|Start a device login]]		\| <code>POST</code> \|\| <code>/api/v1/device/authorizations</code> \|\| None \|\| [[SimTX API v24/Device login#Starting a login\|Start a device login]]
	\|-		\|-
	\| <code>POST</code> \|\| <code>/api/v1/device/token</code> \|\| None \|\| [[SimTX API/Device login#Polling for credentials\|Poll for credentials]]		\| <code>POST</code> \|\| <code>/api/v1/device/token</code> \|\| None \|\| [[SimTX API v24/Device login#Polling for credentials\|Poll for credentials]]
	\|-		\|-
	\| <code>POST</code> \|\| <code>/api/v1/device/refresh</code> \|\| None \|\| [[SimTX API/Device login#Refreshing\|Rotate the credential pair]]		\| <code>POST</code> \|\| <code>/api/v1/device/refresh</code> \|\| None \|\| [[SimTX API v24/Device login#Refreshing\|Rotate the credential pair]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/v1/servers</code> \|\| Bearer \|\| [[SimTX API/Server directory\|List online game servers]]		\| <code>GET</code> \|\| <code>/api/v1/servers</code> \|\| Bearer \|\| [[SimTX API v24/Server directory\|List online game servers]]
	\|-		\|-
	\| <code>POST</code> \|\| <code>/api/v1/game-tickets</code> \|\| Bearer \|\| [[SimTX API/Game tickets\|Obtain a game ticket]]		\| <code>POST</code> \|\| <code>/api/v1/game-tickets</code> \|\| Bearer \|\| [[SimTX API v24/Game tickets\|Obtain a game ticket]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/v1/status</code> \|\| None \|\| [[SimTX API/Public endpoints#Service status\|Service status]]		\| <code>GET</code> \|\| <code>/api/v1/status</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Service status\|Service status]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/v1/profiles</code> \|\| None \|\| [[SimTX API/Public endpoints#Profile search\|Search public profiles]]		\| <code>GET</code> \|\| <code>/api/v1/profiles</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Profile search\|Search public profiles]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/v1/profiles/{handle}</code> \|\| None \|\| [[SimTX API/Public endpoints#Single profile\|Read one public profile]]		\| <code>GET</code> \|\| <code>/api/v1/profiles/{handle}</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Single profile\|Read one public profile]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/v1/releases</code> \|\| None \|\| [[SimTX API/Public endpoints#Releases\|Published transmitter releases]]		\| <code>GET</code> \|\| <code>/api/v1/releases</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Releases\|Published transmitter releases]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/downloads/transmitter-update.properties</code> \|\| None \|\| [[SimTX API/Public endpoints#Update manifest\|Update manifest]]		\| <code>GET</code> \|\| <code>/downloads/transmitter-update.properties</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Update manifest\|Update manifest]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/downloads/{filename}</code> \|\| None \|\| [[SimTX API/Public endpoints#Release downloads\|Release download]]		\| <code>GET</code> \|\| <code>/downloads/{filename}</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Release downloads\|Release download]]
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/v1/network-test/ping</code> \|\| None \|\| [[SimTX API/Public endpoints#Network test\|Latency probe]]		\| <code>GET</code> \|\| <code>/api/v1/network-test/ping</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Network test\|Latency probe]]
	\|-		\|-
	\| <code>POST</code> \|\| <code>/api/v1/network-test/upload</code> \|\| None \|\| [[SimTX API/Public endpoints#Network test\|Upload probe]]		\| <code>POST</code> \|\| <code>/api/v1/network-test/upload</code> \|\| None \|\| [[SimTX API v24/Public endpoints#Network test\|Upload probe]]
	\|}		\|}

Line 54:		Line 54:

	Two kinds of credential are accepted as a bearer:		Two kinds of credential are accepted as a bearer:
	* an '''access credential''' obtained through [[SimTX API/Device login\|device login]], or		* an '''access credential''' obtained through [[SimTX API v24/Device login\|device login]], or
	* a '''personal credential''' created by the user on the account website. It is intended for bots, scripts and other headless software. The user chooses its scopes and expiry, and the secret is displayed once.		* a '''personal credential''' created by the user on the account website. It is intended for bots, scripts and other headless software. The user chooses its scopes and expiry, and the secret is displayed once.

Line 71:		Line 71:
	\| <code>stx_pc1_</code> \|\| Personal credential \|\| Chosen by the user, at most 1 year \|\| Bearer for authenticated endpoints		\| <code>stx_pc1_</code> \|\| Personal credential \|\| Chosen by the user, at most 1 year \|\| Bearer for authenticated endpoints
	\|-		\|-
	\| <code>stx_gt1_</code> \|\| Game ticket \|\| 60 seconds, single use \|\| The game server [[SimTX API/Packets/Handshake\|handshake]]		\| <code>stx_gt1_</code> \|\| Game ticket \|\| 60 seconds, single use \|\| The game server [[SimTX API v24/Packets/Handshake\|handshake]]
	\|}		\|}

Line 80:		Line 80:
	* Persist the refresh credential (or a personal credential) in the operating system's credential store, such as Keychain, Windows Credential Manager or Secret Service.		* Persist the refresh credential (or a personal credential) in the operating system's credential store, such as Keychain, Windows Credential Manager or Secret Service.
	* There is no client-side logout endpoint. Signing out means deleting the stored refresh credential. Users revoke devices and personal credentials on the account website.		* There is no client-side logout endpoint. Signing out means deleting the stored refresh credential. Users revoke devices and personal credentials on the account website.
	* Never send an access, refresh or personal credential to a game server. Game servers only ever see [[SimTX API/Game tickets\|game tickets]].		* Never send an access, refresh or personal credential to a game server. Game servers only ever see [[SimTX API v24/Game tickets\|game tickets]].

	== Errors ==		== Errors ==
Line 114:		Line 114:
	\| 401 \|\| <code>credential_invalid</code> \|\| The bearer credential is unknown, expired, revoked, or belongs to an account that is not active. Refresh once and retry; if that fails, sign in again.		\| 401 \|\| <code>credential_invalid</code> \|\| The bearer credential is unknown, expired, revoked, or belongs to an account that is not active. Refresh once and retry; if that fails, sign in again.
	\|-		\|-
	\| 400 \|\| <code>scope_invalid</code> \|\| A requested scope is not a known [[SimTX API/Permissions\|permission]].		\| 400 \|\| <code>scope_invalid</code> \|\| A requested scope is not a known [[SimTX API v24/Permissions\|permission]].
	\|-		\|-
	\| 400 \|\| <code>ticket_request_invalid</code> \|\| See [[SimTX API/Game tickets#Errors\|Game tickets]].		\| 400 \|\| <code>ticket_request_invalid</code> \|\| See [[SimTX API v24/Game tickets#Errors\|Game tickets]].
	\|-		\|-
	\| 400 \|\| <code>authorization_pending</code>, <code>slow_down</code>, <code>expired_token</code>, <code>access_denied</code>, <code>invalid_grant</code> \|\| Device polling states. See [[SimTX API/Device login#Polling for credentials\|Device login]].		\| 400 \|\| <code>authorization_pending</code>, <code>slow_down</code>, <code>expired_token</code>, <code>access_denied</code>, <code>invalid_grant</code> \|\| Device polling states. See [[SimTX API v24/Device login#Polling for credentials\|Device login]].
	\|-		\|-
	\| 401 \|\| <code>invalid_grant</code>, <code>refresh_reuse_detected</code> \|\| Refresh failures. See [[SimTX API/Device login#Refreshing\|Device login]].		\| 401 \|\| <code>invalid_grant</code>, <code>refresh_reuse_detected</code> \|\| Refresh failures. See [[SimTX API v24/Device login#Refreshing\|Device login]].
	\|-		\|-
	\| 404 \|\| <code>profile_not_found</code>, <code>release_artifact_not_found</code>, <code>release_manifest_unavailable</code> \|\| The requested public resource does not exist.		\| 404 \|\| <code>profile_not_found</code>, <code>release_artifact_not_found</code>, <code>release_manifest_unavailable</code> \|\| The requested public resource does not exist.
Line 163:		Line 163:

	== See also ==		== See also ==
	* [[SimTX API/Device login]]: the sign-in flow for desktop and command-line software.		* [[SimTX API v24/Device login]]: the sign-in flow for desktop and command-line software.
	* [[SimTX API/Game tickets]]: how a credential becomes a game server connection.		* [[SimTX API v24/Game tickets]]: how a credential becomes a game server connection.
	* [[SimTX API/Permissions]]: scopes and numeric capabilities.		* [[SimTX API v24/Permissions]]: scopes and numeric capabilities.

	{{SimTX API navbox}}		{{SimTX API v24 navbox}}
	[[Category:SimTX API]]		[[Category:SimTX API v24]]
	[[Category:SimTX API account service]]		[[Category:SimTX API v24 account service]]