Editing SimTX API v24/Account service

{{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 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 v24/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 v24/Device login#Starting a login|Start a device login]]
|-
| <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 v24/Device login#Refreshing|Rotate the credential pair]]
|-
| <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 v24/Game tickets|Obtain a game ticket]]
|-
| <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 v24/Public endpoints#Profile search|Search public profiles]]
|-
| <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 v24/Public endpoints#Releases|Published transmitter releases]]
|-
| <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 v24/Public endpoints#Release downloads|Release download]]
|-
| <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 v24/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 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.

=== 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 v24/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 v24/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 v24/Permissions|permission]].
|-
| 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 v24/Device login#Polling for credentials|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.
|-
| 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 v24/Device login]]: the sign-in flow for desktop and command-line software.
* [[SimTX API v24/Game tickets]]: how a credential becomes a game server connection.
* [[SimTX API v24/Permissions]]: scopes and numeric capabilities.

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