Editing SimTX API v24/Game tickets

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

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

== 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 v24/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 v24 navbox}}
[[Category:SimTX API v24]]
[[Category:SimTX API v24 account service]]