Editing SimTX API/Account service

{{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, manages persistent stations and satellites, lists the game servers that are online, and exchanges a credential for the single-use '''game ticket''' that a game server accepts in the [[SimTX API/Connection and handshake|hello]]. It also serves a small set of public, unauthenticated endpoints.

A client that only '''receives''' at an ad-hoc site does not need the account service at all, apart from discovering a server address. A client that '''transmits''', receives through a station, manages stations 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>POST</code> || <code>/api/v1/stations</code> || Bearer || [[SimTX API/Station endpoints#Listing stations|List your stations]], [[SimTX API/Station endpoints#Creating a ground station|create a ground station]]
|-
| <code>GET</code>, <code>PATCH</code>, <code>DELETE</code> || <code>/api/v1/stations/{id}</code> || Bearer || [[SimTX API/Station endpoints#Reading, editing and deleting|Read, edit or delete a station]]
|-
| <code>POST</code>, <code>PATCH</code>, <code>DELETE</code> || <code>/api/v1/stations/{id}/antennas</code>... || Bearer || [[SimTX API/Station endpoints#Antennas and rigs|Manage antennas]]
|-
| <code>POST</code>, <code>PATCH</code>, <code>DELETE</code> || <code>/api/v1/stations/{id}/rigs</code>... || Bearer || [[SimTX API/Station endpoints#Antennas and rigs|Manage rigs]]
|-
| <code>POST</code> || <code>/api/v1/satellites</code> || Bearer || [[SimTX API/Station endpoints#Launching a satellite|Launch a satellite]]
|-
| <code>POST</code> || <code>/api/v1/stations/{id}/deorbit/preview</code> || Bearer || [[SimTX API/Station endpoints#Deorbiting|Preview a deorbit burn]]
|-
| <code>POST</code> || <code>/api/v1/stations/{id}/deorbit</code> || Bearer || [[SimTX API/Station endpoints#Deorbiting|Deorbit a satellite]]
|-
| <code>GET</code> || <code>/api/v1/satellites</code> || None || [[SimTX API/Public endpoints#Public satellites|Public satellites]]
|-
| <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 client 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.

== 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. Null fields are omitted. Clients must ignore unknown response fields.
* '''Caching.''' Every <code>/api/</code> response carries <code>Cache-Control: no-store</code>, except the public satellite list, which supports <code>ETag</code> revalidation.
* '''Timeouts.''' Use a 5 second connect timeout and a 10 second request timeout.
* '''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.
* '''Body size.''' Station, antenna, rig and launch bodies are limited to 2 MiB (<code>413 request_too_large</code>).

== 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.

What a credential may do is the intersection of its '''scope''' and the account's [[SimTX API/Permissions|permissions]]. Station writes, launches and deorbit burns need the scope <code>station.manage</code>; reading stations, previewing a deorbit and minting station-bound tickets need only an account credential.

=== 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/ClientHello|hello]]
|}

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>.

=== Storing credentials ===
* Keep the access credential in memory only. It expires after ten minutes.
* 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>, and a missing scope as <code>fieldErrors.scope</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]].
|-
| 403 || <code>scope_required</code> || The credential's scope lacks a permission the endpoint needs; <code>fieldErrors.scope</code> names it. Sign the user in again with the wider scope.
|-
| 400 || <code>ticket_request_invalid</code> || See [[SimTX API/Game tickets#Errors|Game tickets]].
|-
| 400, 403, 404, 409 || <code>station_invalid</code>, <code>station_not_found</code>, <code>station_sealed</code> and others || See [[SimTX API/Station endpoints#Errors|Station endpoints]].
|-
| 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.
|-
| 413 || <code>request_too_large</code> || The request body is over the limit.
|-
| 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>station-read</code> || <code>GET /api/v1/stations</code>, <code>GET /api/v1/stations/{id}</code>, <code>POST .../deorbit/preview</code> || 240
|-
| <code>station-write</code> || Every station, antenna, rig, launch and deorbit write || 120
|-
| <code>public-satellites</code> || <code>GET /api/v1/satellites</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/Station endpoints]]: stations, satellites and deorbiting.
* [[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]]