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

2026-10-24T16:13:37Z

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

← Older revision		Revision as of 16:13, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	'''Device login''' is the sign-in flow for software that cannot, or should not, handle a SimTX password itself: desktop applications, command-line tools and headless bridges. The software shows the user a short code, the user approves it in a browser while signed in to SimTX, and the software receives an [[SimTX API/Account service#Credential formats\|access and refresh credential]].		'''Device login''' is the sign-in flow for software that cannot, or should not, handle a SimTX password itself: desktop applications, command-line tools and headless bridges. The software shows the user a short code, the user approves it in a browser while signed in to SimTX, and the software receives an [[SimTX API v24/Account service#Credential formats\|access and refresh credential]].

	The flow is modelled on the OAuth 2.0 device authorization grant (RFC 8628), with two differences: requests and responses are JSON rather than form-encoded, and the endpoint and field names are SimTX's own. Generic OAuth libraries will therefore not work without adaptation.		The flow is modelled on the OAuth 2.0 device authorization grant (RFC 8628), with two differences: requests and responses are JSON rather than form-encoded, and the endpoint and field names are SimTX's own. Generic OAuth libraries will therefore not work without adaptation.

	Software that only receives does not need to sign in at all. Bots that run unattended should normally use a personal credential instead (see [[SimTX API/Account service#Authentication\|Authentication]]).		Software that only receives does not need to sign in at all. Bots that run unattended should normally use a personal credential instead (see [[SimTX API v24/Account service#Authentication\|Authentication]]).

	== Sequence ==		== Sequence ==
Line 38:		Line 38:
	\| <code>clientName</code> \|\| string \|\| No \|\| Name shown to the user on the approval page and in their device list. Truncated to 80 characters. Defaults to <code>SimTX client</code> when blank.		\| <code>clientName</code> \|\| string \|\| No \|\| Name shown to the user on the approval page and in their device list. Truncated to 80 characters. Defaults to <code>SimTX client</code> when blank.
	\|-		\|-
	\| <code>scope</code> \|\| string \|\| No \|\| Space-separated list of [[SimTX API/Permissions\|permission identifiers]] the credential may use. An empty or missing scope requests every permission the account holds at the moment of approval. Unknown identifiers are rejected with <code>400 scope_invalid</code>.		\| <code>scope</code> \|\| string \|\| No \|\| Space-separated list of [[SimTX API v24/Permissions\|permission identifiers]] the credential may use. An empty or missing scope requests every permission the account holds at the moment of approval. Unknown identifiers are rejected with <code>400 scope_invalid</code>.
	\|}		\|}

Line 185:		Line 185:

	== See also ==		== See also ==
	* [[SimTX API/Account service]]: errors, credential formats and rate limits.		* [[SimTX API v24/Account service]]: errors, credential formats and rate limits.
	* [[SimTX API/Game tickets]]: the next step for a client that wants to transmit.		* [[SimTX API v24/Game tickets]]: the next step for a client that wants to transmit.

	{{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]]

Clanker: Clanker moved page SimTX API/Device login to SimTX API v24/Device login: Archive the v24 protocol reference

2026-10-24T16:12:20Z

Clanker moved page SimTX API/Device login to SimTX API v24/Device login: Archive the v24 protocol reference

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

Clanker: SimTX API documentation

2026-10-24T09:50:19Z

SimTX API documentation

New page

{{SimTX API navigation}}
'''Device login''' is the sign-in flow for software that cannot, or should not, handle a SimTX password itself: desktop applications, command-line tools and headless bridges. The software shows the user a short code, the user approves it in a browser while signed in to SimTX, and the software receives an [[SimTX API/Account service#Credential formats|access and refresh credential]].

The flow is modelled on the OAuth 2.0 device authorization grant (RFC 8628), with two differences: requests and responses are JSON rather than form-encoded, and the endpoint and field names are SimTX's own. Generic OAuth libraries will therefore not work without adaptation.

Software that only receives does not need to sign in at all. Bots that run unattended should normally use a personal credential instead (see [[SimTX API/Account service#Authentication|Authentication]]).

== Sequence ==
<syntaxhighlight lang="text">
Client auth.simtx.net User's browser
| POST /device/authorizations | |
|---------------------------------->| |
| 201 deviceCode, userCode, URI | |
|<----------------------------------| |
| show userCode, open URI ------------------------------------------->|
| | user signs in and approves |
| POST /device/token (every 5 s) |<---------------------------------|
|---------------------------------->| |
| 400 authorization_pending | |
|<----------------------------------| |
| POST /device/token | |
|---------------------------------->| |
| 200 access + refresh credential | |
|<----------------------------------| |
</syntaxhighlight>

== Starting a login ==
<code>POST /api/v1/device/authorizations</code>. No authentication.

=== Request ===
<syntaxhighlight lang="json">
{ "clientName": "Example SDR Client", "scope": "game.transmit" }
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Required !! Description
|-
| <code>clientName</code> || string || No || Name shown to the user on the approval page and in their device list. Truncated to 80 characters. Defaults to <code>SimTX client</code> when blank.
|-
| <code>scope</code> || string || No || Space-separated list of [[SimTX API/Permissions|permission identifiers]] the credential may use. An empty or missing scope requests every permission the account holds at the moment of approval. Unknown identifiers are rejected with <code>400 scope_invalid</code>.
|}

Request the smallest scope that does the job. A transmitter needs <code>game.transmit</code>. A tool that publishes extensions needs <code>catalog.publish</code>.

=== Response ===
<code>201 Created</code>:

<syntaxhighlight lang="json">
{
"deviceCode": "stx_dc1_9a1f…",
"userCode": "QZ7K-M4TP",
"verificationUri": "https://auth.simtx.net/device",
"verificationUriComplete": "https://auth.simtx.net/device?code=QZ7K-M4TP",
"expiresIn": 600,
"interval": 5,
"expiresAt": "2026-10-24T12:10:00Z"
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>deviceCode</code> || string || Secret used to poll for the result. Keep it private; do not show it to the user.
|-
| <code>userCode</code> || string || Code the user confirms in the browser.
|-
| <code>verificationUri</code> || string || Page where the user types the code.
|-
| <code>verificationUriComplete</code> || string || Same page with the code pre-filled. Open this one if the client can launch a browser.
|-
| <code>expiresIn</code> || integer || Seconds until the device code expires (600).
|-
| <code>interval</code> || integer || Minimum seconds between polls (5).
|-
| <code>expiresAt</code> || string || Absolute expiry time.
|}

Display <code>userCode</code> prominently and open <code>verificationUriComplete</code>. The user can then compare the code on the page with the code in the application before approving.

== Polling for credentials ==
<code>POST /api/v1/device/token</code>. No authentication.

<syntaxhighlight lang="json">
{ "deviceCode": "stx_dc1_9a1f…" }
</syntaxhighlight>

=== Success ===
<code>200 OK</code> with a credential pair:

<syntaxhighlight lang="json">
{
"accessCredential": "stx_at1_5c0e…",
"refreshCredential": "stx_rt1_b77d…",
"credentialType": "Bearer",
"expiresIn": 600,
"scope": "game.transmit"
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>accessCredential</code> || string || Bearer credential, valid for <code>expiresIn</code> seconds.
|-
| <code>refreshCredential</code> || string || Used once to obtain the next pair.
|-
| <code>credentialType</code> || string || Always <code>Bearer</code>.
|-
| <code>expiresIn</code> || integer || Access credential lifetime in seconds (600).
|-
| <code>scope</code> || string || Space-separated scopes actually granted.
|}

A device code can be exchanged exactly once. Polling again after success returns <code>access_denied</code>.

=== Not ready yet ===
Until the user acts, the service answers <code>400</code> with one of the following codes. Every one of these responses includes the interval the client must now use, as a string, in <code>fieldErrors.interval</code>.

{| class="wikitable"
! <code>code</code> !! Meaning !! Client action
|-
| <code>authorization_pending</code> || The user has not approved or denied yet. || Wait <code>interval</code> seconds and poll again.
|-
| <code>slow_down</code> || The poll arrived sooner than <code>interval</code> seconds after the previous one. The interval has been increased by 5 seconds. || Adopt <code>fieldErrors.interval</code> for all later polls.
|-
| <code>expired_token</code> || Ten minutes have passed. || Start a new login.
|-
| <code>access_denied</code> || The user denied the request, or the code was already exchanged. || Stop.
|-
| <code>invalid_grant</code> || The device code is unknown. || Start a new login.
|}

A client that ignores <code>slow_down</code> and keeps its old pace is told to slow down on every single poll, and each warning adds another five seconds. Such a client never receives credentials. Read the interval from the response.

== Refreshing ==
<code>POST /api/v1/device/refresh</code>. No authentication.

<syntaxhighlight lang="json">
{ "refreshCredential": "stx_rt1_b77d…" }
</syntaxhighlight>

On success the response is <code>200 OK</code> with a new credential pair in the same format as above. '''The refresh credential rotates on every use.''' Store the new one immediately and discard the old one.

{| class="wikitable"
! HTTP !! <code>code</code> !! Meaning
|-
| 401 || <code>invalid_grant</code> || The refresh credential is unknown, expired, or its device session was revoked. Sign in again.
|-
| 401 || <code>refresh_reuse_detected</code> || A refresh credential that had already been used was presented again. The service treats this as theft and revokes the whole device session. Sign in again.
|}

Refresh credentials expire after 30 days without use and 180 days after the original sign-in, whichever comes first.

== Recommended client behaviour ==
# On start-up, load the stored refresh credential. If there is none, run device login.
# Refresh to obtain an access credential. Keep the access credential in memory.
# Refresh again when fewer than about 30 seconds of the access credential remain.
# When any endpoint answers <code>401 credential_invalid</code>, refresh once and repeat the request. If the refresh fails, delete the stored credential and run device login.
# Serialise refreshes. Two threads refreshing with the same refresh credential at once will trigger <code>refresh_reuse_detected</code>, and the user will have to sign in again.

== Example ==
A complete login with <code>curl</code> and <code>jq</code>:

<syntaxhighlight lang="bash">
AUTH=https://auth.simtx.net

start=$(curl -s -X POST "$AUTH/api/v1/device/authorizations" \
-H 'Content-Type: application/json' \
-d '{"clientName":"curl demo","scope":"game.transmit"}')
device=$(jq -r .deviceCode <<<"$start")
interval=$(jq -r .interval <<<"$start")
echo "Open $(jq -r .verificationUriComplete <<<"$start") and confirm $(jq -r .userCode <<<"$start")"

while sleep "$interval"; do
reply=$(curl -s -X POST "$AUTH/api/v1/device/token" \
-H 'Content-Type: application/json' -d "{\"deviceCode\":\"$device\"}")
case $(jq -r '.code // "ok"' <<<"$reply") in
ok) jq . <<<"$reply"; break ;;
authorization_pending) ;;
slow_down) interval=$(jq -r .fieldErrors.interval <<<"$reply") ;;
*) echo "login failed: $reply"; exit 1 ;;
esac
done
</syntaxhighlight>

== See also ==
* [[SimTX API/Account service]]: errors, credential formats and rate limits.
* [[SimTX API/Game tickets]]: the next step for a client that wants to transmit.

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

SimTX API v24/Device login - Revision history

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

Clanker: Clanker moved page SimTX API/Device login to SimTX API v24/Device login: Archive the v24 protocol reference

Clanker: SimTX API documentation