Editing SimTX API v24/Permissions

{{SimTX API v24 navigation}}
SimTX authorisation uses one set of '''permission identifiers''' (also called capabilities). An account gains them from its roles and from direct grants. A credential's '''scope''' can narrow them further, and an account restriction can remove them. Game servers receive the resulting set in the [[SimTX API v24/Packets/HandshakeResult|HandshakeResult]].

== Boolean permissions ==
A boolean permission authorises an action.

{| class="wikitable"
! Identifier !! Grants !! Relevant to
|-
| <code>game.transmit</code> || Opening transmitter sessions (roles 2 and 3). || [[SimTX API v24/Transmitter session]]
|-
| <code>catalog.publish</code> || Uploading to and deleting from the extension catalog. Also required to obtain a <code>control</code> game ticket. || [[SimTX API v24/Extension catalog protocol]]
|-
| <code>session.queue_skip</code> || Never waiting in the transmitter queue. When the server is full, such a request is rejected instead of queued. || [[SimTX API v24/Packets/TxQueue|TxQueue]]
|-
| <code>tx.pa_override</code> || The amplifier's nominal power follows the requested power instead of the simulated equipment's rating. || [[SimTX API v24/Packets/TransmitterSessionRequest|TransmitterSessionRequest]]
|-
| <code>monitor.any</code> || Monitoring any transmitter, solo receivers, and client addresses in health reports. || [[SimTX API v24/Moderation session]]
|-
| <code>moderation.manage</code> || The moderation role: kicks, bans, banners, stations with addresses. || [[SimTX API v24/Moderation session]]
|-
| <code>proxy.forward_client_ip</code> || Sending [[SimTX API v24/Packets/ForwardedClientAddress|ForwardedClientAddress]] on behalf of proxied receivers. || [[SimTX API v24/Receiver session]]
|-
| <code>accounts.admin</code>, <code>awards.manage</code> || Administration of the account service. Not used by game servers. ||
|}

Which of these an account holds depends on its roles. The HandshakeResult of an authenticated connection lists them.

== Numeric capabilities ==
A numeric capability encodes a limit in its last segment. When several roles grant values from the same family, the largest value applies.

{| class="wikitable"
! Family !! Example !! Meaning !! Range
|-
| <code>game.max_stations.N</code> || <code>game.max_stations.8</code> || At most ''N'' simultaneous transmitters for the account. || 1–10,000
|-
| <code>game.max_receivers.N</code> || <code>game.max_receivers.4</code> || At most ''N'' simultaneous authenticated receivers. || 1–10,000
|-
| <code>game.max_sessions.N</code> || <code>game.max_sessions.12</code> || At most ''N'' simultaneous authenticated receiver and transmitter sessions in total. || 1–10,000
|-
| <code>tx.pa_limit.N</code> || <code>tx.pa_limit.400</code> || Transmitter power is capped at ''N'' watts, both in the request and in live updates. || 1–1,000,000
|}

An account without any <code>game.max_stations</code> capability may run 3 transmitters. Account capabilities are applied ''in addition to'' each server's own limits and cannot raise them. See [[SimTX API v24/Limits and errors]].

Client software should read these values from the HandshakeResult and show them, for example as the maximum of a power slider, rather than letting users discover them by trial.

== Scopes ==
A credential's scope is a list of permission identifiers, chosen during [[SimTX API v24/Device login|device login]] or when creating a personal credential. A scope never adds permissions. When a game ticket is requested, the service uses the permissions that are both in the credential's scope and held by the account on that server.

* An empty scope at device login means every permission the account held when the user approved the login.
* Unknown identifiers are rejected with <code>400 scope_invalid</code>. Numeric capabilities are accepted in scopes if they are well formed and within range.
* Request the minimum. A transmitter needs <code>game.transmit</code>; a catalog publishing tool needs <code>catalog.publish</code>; a receiver needs no credential at all.

== Server-specific grants ==
Roles and grants can be limited to a single server. They take effect only in tickets for that server, and appear only in the HandshakeResult of connections to it.

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