Editing SimTX API/Account service (section)

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