SimTX API v24/Game tickets - Revision history

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

2026-10-24T16:13:42Z

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}}
	A '''game ticket''' is a short-lived, single-use credential that a client presents to a game server in the [[SimTX API/Packets/Handshake\|Handshake]]. Tickets keep reusable credentials away from game servers: the server only ever sees a ticket that is worthless sixty seconds later.		A '''game ticket''' is a short-lived, single-use credential that a client presents to a game server in the [[SimTX API v24/Packets/Handshake\|Handshake]]. Tickets keep reusable credentials away from game servers: the server only ever sees a ticket that is worthless sixty seconds later.

	Anonymous receiver and control connections do not need a ticket.		Anonymous receiver and control connections do not need a ticket.
Line 16:		Line 16:
	! Field !! Type !! Description		! Field !! Type !! Description
	\|-		\|-
	\| <code>serverId</code> \|\| string \|\| A <code>serverId</code> from the [[SimTX API/Server directory\|server directory]].		\| <code>serverId</code> \|\| string \|\| A <code>serverId</code> from the [[SimTX API v24/Server directory\|server directory]].
	\|-		\|-
	\| <code>role</code> \|\| string \|\| The protocol role the ticket will be used for. See the table below.		\| <code>role</code> \|\| string \|\| The protocol role the ticket will be used for. See the table below.
Line 40:		Line 40:
	There is no ticket role for <code>TIMESTAMPED_RECEIVER</code> (role 6). That role is anonymous only.		There is no ticket role for <code>TIMESTAMPED_RECEIVER</code> (role 6). That role is anonymous only.

	An authenticated <code>control</code> connection is only needed to publish to or delete from the [[SimTX API/Extension catalog protocol\|extension catalog]]. Reading the station list, maps and the catalog works anonymously.		An authenticated <code>control</code> connection is only needed to publish to or delete from the [[SimTX API v24/Extension catalog protocol\|extension catalog]]. Reading the station list, maps and the catalog works anonymously.

	The permission check uses the intersection of the credential's scopes and the account's effective permissions on that server. A credential created with scope <code>catalog.publish</code> cannot obtain a <code>tx-audio</code> ticket, even if the account itself may transmit.		The permission check uses the intersection of the credential's scopes and the account's effective permissions on that server. A credential created with scope <code>catalog.publish</code> cannot obtain a <code>tx-audio</code> ticket, even if the account itself may transmit.
Line 63:		Line 63:
	* It is bound to the requested <code>serverId</code> and <code>role</code>. Presenting it to another server or with another role fails with <code>CREDENTIAL_INVALID</code>.		* It is bound to the requested <code>serverId</code> and <code>role</code>. Presenting it to another server or with another role fails with <code>CREDENTIAL_INVALID</code>.
	* Fetch a new ticket for every connection, including every reconnect. Do not fetch tickets in advance.		* Fetch a new ticket for every connection, including every reconnect. Do not fetch tickets in advance.
	* A ticket does not carry the user's identity in readable form. The server resolves it and returns the account in [[SimTX API/Packets/HandshakeResult\|HandshakeResult]].		* A ticket does not carry the user's identity in readable form. The server resolves it and returns the account in [[SimTX API v24/Packets/HandshakeResult\|HandshakeResult]].

	== Errors ==		== Errors ==
Line 90:		Line 90:
	</syntaxhighlight>		</syntaxhighlight>

	{{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/Game tickets to SimTX API v24/Game tickets: Archive the v24 protocol reference

2026-10-24T16:12:36Z

Clanker moved page SimTX API/Game tickets to SimTX API v24/Game tickets: Archive the v24 protocol reference

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

Clanker: SimTX API documentation

2026-10-24T09:51:03Z

SimTX API documentation

New page

{{SimTX API navigation}}
A '''game ticket''' is a short-lived, single-use credential that a client presents to a game server in the [[SimTX API/Packets/Handshake|Handshake]]. Tickets keep reusable credentials away from game servers: the server only ever sees a ticket that is worthless sixty seconds later.

Anonymous receiver and control connections do not need a ticket.

== Request ==
<code>POST /api/v1/game-tickets</code>

Requires a bearer credential. Rate limit: 120 requests per minute per IP address.

<syntaxhighlight lang="json">
{ "serverId": "argon", "role": "tx-audio" }
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>serverId</code> || string || A <code>serverId</code> from the [[SimTX API/Server directory|server directory]].
|-
| <code>role</code> || string || The protocol role the ticket will be used for. See the table below.
|}

=== Roles ===
The ticket is bound to one role. The role string in the request must correspond to the role byte later sent in the handshake.

{| class="wikitable"
! Ticket <code>role</code> !! Handshake role byte !! Permission required to obtain the ticket
|-
| <code>receiver</code> || 1 <code>RECEIVER</code> || None
|-
| <code>tx-audio</code> || 2 <code>TX_AUDIO</code> || <code>game.transmit</code>
|-
| <code>tx-generated</code> || 3 <code>TX_GENERATED</code> || <code>game.transmit</code>
|-
| <code>control</code> || 4 <code>CONTROL</code> || <code>catalog.publish</code>
|-
| <code>moderation</code> || 5 <code>MODERATION</code> || <code>moderation.manage</code>
|}

There is no ticket role for <code>TIMESTAMPED_RECEIVER</code> (role 6). That role is anonymous only.

An authenticated <code>control</code> connection is only needed to publish to or delete from the [[SimTX API/Extension catalog protocol|extension catalog]]. Reading the station list, maps and the catalog works anonymously.

The permission check uses the intersection of the credential's scopes and the account's effective permissions on that server. A credential created with scope <code>catalog.publish</code> cannot obtain a <code>tx-audio</code> ticket, even if the account itself may transmit.

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

<syntaxhighlight lang="json">
{ "ticket": "stx_gt1_7e21…", "expiresAt": "2026-10-24T12:01:00Z" }
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>ticket</code> || string || The ticket. Place it in the <code>credential</code> field of the handshake with <code>authKind = 1</code>.
|-
| <code>expiresAt</code> || string || Expiry time, 60 seconds after issue.
|}

== Rules ==
* A ticket is valid for '''60 seconds''' and can be used '''once'''.
* It is bound to the requested <code>serverId</code> and <code>role</code>. Presenting it to another server or with another role fails with <code>CREDENTIAL_INVALID</code>.
* Fetch a new ticket for every connection, including every reconnect. Do not fetch tickets in advance.
* A ticket does not carry the user's identity in readable form. The server resolves it and returns the account in [[SimTX API/Packets/HandshakeResult|HandshakeResult]].

== Errors ==
All validation failures use HTTP <code>400</code> with code <code>ticket_request_invalid</code>. The <code>message</code> distinguishes the cause:

{| class="wikitable"
! <code>message</code> !! Cause
|-
| <code>serverId and role are required</code> || A field is missing or blank.
|-
| <code>unknown protocol role</code> || <code>role</code> is not one of the strings above.
|-
| <code>unknown, disabled, or offline server</code> || The server is not in the directory right now.
|-
| <code>credential is not authorized for the requested protocol role</code> || The credential's scopes, or the account's permissions, do not include the permission the role requires.
|}

<code>401 credential_missing</code> and <code>401 credential_invalid</code> apply as for every authenticated endpoint.

== Example ==
<syntaxhighlight lang="bash">
curl -s -X POST https://auth.simtx.net/api/v1/game-tickets \
-H "Authorization: Bearer $SIMTX_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"serverId":"argon","role":"tx-audio"}'
</syntaxhighlight>

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