SimTX API v24/Game tickets: Difference between revisions

Latest revision as of 16:13, 24 October 2026

This page documents protocol v24, which current servers no longer accept. See SimTX API for v25.

v24 overviewQuick startAccount serviceHandshakeAll packetsData typesLimits and errorsCurrent reference (v25)

A game ticket is a short-lived, single-use credential that a client presents to a game server in the 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[edit | edit source]

POST /api/v1/game-tickets

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

{ "serverId": "argon", "role": "tx-audio" }

Field	Type	Description
`serverId`	string	A `serverId` from the server directory.
`role`	string	The protocol role the ticket will be used for. See the table below.

Roles[edit | edit source]

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

Ticket `role`	Handshake role byte	Permission required to obtain the ticket
`receiver`	1 `RECEIVER`	None
`tx-audio`	2 `TX_AUDIO`	`game.transmit`
`tx-generated`	3 `TX_GENERATED`	`game.transmit`
`control`	4 `CONTROL`	`catalog.publish`
`moderation`	5 `MODERATION`	`moderation.manage`

There is no ticket role for TIMESTAMPED_RECEIVER (role 6). That role is anonymous only.

An authenticated control connection is only needed to publish to or delete from the 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 catalog.publish cannot obtain a tx-audio ticket, even if the account itself may transmit.

Response[edit | edit source]

201 Created:

{ "ticket": "stx_gt1_7e21…", "expiresAt": "2026-10-24T12:01:00Z" }

Field	Type	Description
`ticket`	string	The ticket. Place it in the `credential` field of the handshake with `authKind = 1`.
`expiresAt`	string	Expiry time, 60 seconds after issue.

Rules[edit | edit source]

A ticket is valid for 60 seconds and can be used once.
It is bound to the requested serverId and role. Presenting it to another server or with another role fails with CREDENTIAL_INVALID.
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 HandshakeResult.

Errors[edit | edit source]

All validation failures use HTTP 400 with code ticket_request_invalid. The message distinguishes the cause:

`message`	Cause
`serverId and role are required`	A field is missing or blank.
`unknown protocol role`	`role` is not one of the strings above.
`unknown, disabled, or offline server`	The server is not in the directory right now.
`credential is not authorized for the requested protocol role`	The credential's scopes, or the account's permissions, do not include the permission the role requires.

401 credential_missing and 401 credential_invalid apply as for every authenticated endpoint.

Example[edit | edit source]

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"}'

SimTX API v24 reference (protocol v24, archived)
Start	OverviewQuick startData typesLimits and errorsPacket list
Account service	OverviewDevice loginServer directoryGame ticketsPermissionsPublic endpoints
Game protocol	Connection and handshakeReceiver sessionTransmitter sessionControl sessionCatalogModeration
Handshake	HandshakeHandshakeResult
Receiver	ReceiverSessionRequestReceiverRetuneForwardedClientAddressIqStreamDescriptorIqBlockTimedIqBlock
Transmitter	TransmitterSessionRequestSampleBlockTxModeInfoTxUpdateTxQueueTxAcceptTxRejectTxKickTxTelemetryTxUpdateAck
Control	ControlAckBannerListStationsStationListServerHealthRequestServerHealthReportCoverageMapRequestCoverageMapResponseWeatherMapRequestWeatherMapResponseStartMonitorStopMonitorMonitorBlockMonitorEnd
Catalog	CatalogListRequestCatalogListCatalogFetchCatalogEntryCatalogUploadCatalogUploadResultCatalogDeleteCatalogDeleteResult
Moderation	KickRequestKickResultIpModerationRequestIpModerationResultBroadcastBannerModerationErrorStationImpactList
Current	Protocol v25 reference

@@ 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.
@@ Line 16: / Line 16: @@
 ! 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.
@@ Line 40: / Line 40: @@
 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.
@@ 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>.
 * 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 ==
@@ Line 90: / Line 90: @@
 </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]]