Editing SimTX API/Game tickets (section)

== 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",
  "stationId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "antennaId": "9b2c1e47-2f0a-4c55-8d1e-6a7b8c9d0e1f"
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Required !! Description
|-
| <code>serverId</code> || string || Yes || A <code>serverId</code> from the [[SimTX API/Server directory|server directory]].
|-
| <code>role</code> || string || Yes || The protocol role the ticket will be used for. See [[#Roles|Roles]].
|-
| <code>stationId</code> || string (UUID) || No || Bind the ticket to a persistent station. Transmitter roles need a station the account owns; <code>receiver</code> also accepts another account's PUBLIC station.
|-
| <code>antennaId</code> || string (UUID) || No || The station's antenna. Default: its first antenna by ordinal.
|-
| <code>rigId</code> || string (UUID) || No || The station's rig. Default: its first rig by ordinal, or none when the station has no rigs.
|}

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

{| class="wikitable"
! Ticket <code>role</code> !! Hello <code>role</code> !! Permission required to obtain the ticket !! Station binding
|-
| <code>receiver</code> || <code>ROLE_RECEIVER</code> (1) || None || Optional
|-
| <code>tx-audio</code> || <code>ROLE_TX_AUDIO</code> (2) || <code>game.transmit</code> || Optional; transmitting through a station needs it
|-
| <code>tx-generated</code> || <code>ROLE_TX_GENERATED</code> (3) || <code>game.transmit</code> || Optional; transmitting through a station needs it
|-
| <code>control</code> || <code>ROLE_CONTROL</code> (4) || <code>catalog.publish</code> || Not allowed
|-
| <code>moderation</code> || <code>ROLE_MODERATION</code> (5) || <code>moderation.manage</code> || Not allowed
|}

An authenticated <code>control</code> connection is only needed to publish to or delete from the [[SimTX API/Extension catalog protocol|extension catalog]] and to monitor one's own transmitters. Reading the station list, maps, ephemerides, passes 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.