Editing SimTX API/Permissions

{{SimTX API 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/Packets/ServerHello|ServerHello]].

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

{| class="wikitable"
! Identifier !! Grants !! Relevant to
|-
| <code>game.transmit</code> || Opening transmitter sessions (<code>ROLE_TX_AUDIO</code>, <code>ROLE_TX_GENERATED</code>). || [[SimTX API/Transmitter session]]
|-
| <code>station.manage</code> || Creating, editing and deleting stations, launching satellites and deorbiting them. Granted to members. Reading stations, previewing a deorbit and minting station-bound tickets do not need it. || [[SimTX API/Station endpoints]]
|-
| <code>catalog.publish</code> || Uploading to and deleting from the extension catalog. Also required to obtain a <code>control</code> game ticket. || [[SimTX API/Extension catalog protocol]]
|-
| <code>session.queue_skip</code> || Never waiting in the transmitter queue. When the server is full, such a start is refused with <code>LIMIT_REACHED</code> instead of queued. || [[SimTX API/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/Packets/TransmitterStart|TransmitterStart]]
|-
| <code>tx.adhoc</code> || Transmitting from an ad-hoc site without a persistent station, whatever the server's ad-hoc policy. Held by service integrations, not by user accounts. || [[SimTX API/Stations#Ad-hoc transmitters|Ad-hoc transmitters]]
|-
| <code>monitor.any</code> || Monitoring any transmitter, solo receivers, and client addresses in health reports. || [[SimTX API/Moderation session]]
|-
| <code>moderation.manage</code> || The moderation role: kicks, bans, banners, station lists with addresses. || [[SimTX API/Moderation session]]
|-
| <code>proxy.forward_client_ip</code> || Sending [[SimTX API/Packets/ForwardedClientAddress|ForwardedClientAddress]] on behalf of proxied receivers. || [[SimTX API/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 ServerHello 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'' transmitters on air at once for the account. Despite the name, this counts transmitter sessions, not owned stations. || 1 to 10,000
|-
| <code>game.max_receivers.N</code> || <code>game.max_receivers.4</code> || At most ''N'' simultaneous authenticated receivers. || 1 to 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 to 10,000
|-
| <code>tx.pa_limit.N</code> || <code>tx.pa_limit.400</code> || Transmitter power is capped at ''N'' watts, in the start and in live updates. A bound rig with a lower <code>paMaxWatts</code> caps it further. || 1 to 1,000,000
|-
| <code>game.owned_stations.N</code> || <code>game.owned_stations.100</code> || At most ''N'' active stations owned, ground and satellite together. || 1 to 10,000
|-
| <code>game.owned_satellites.N</code> || <code>game.owned_satellites.25</code> || At most ''N'' active satellites owned. Deorbiting satellites count until they reenter. || 1 to 10,000
|-
| <code>game.station_sessions.N</code> || <code>game.station_sessions.16</code> || Each of a station's session limits (<code>maxSessions</code>, <code>maxTransmitters</code>, <code>maxReceivers</code>) is clamped to ''N''. || 1 to 10,000
|}

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

Default station quotas: members have <code>game.owned_stations.100</code>, <code>game.owned_satellites.25</code> and <code>game.station_sessions.16</code>; supporters 500, 100 and 64.

Client software should read these values from the ServerHello and show them, for example as the maximum of a power slider.

== Scopes ==
A credential's scope is a list of permission identifiers, chosen during [[SimTX API/Device login|device login]] or when creating a personal credential. A scope never adds permissions. Each request is authorised with the permissions that are both in the credential's scope and held by the account.

* 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.
* An endpoint that needs a permission the scope lacks answers <code>403 scope_required</code> with <code>fieldErrors.scope</code>.
* Request the minimum. A transmitter needs <code>game.transmit</code>; a station editor <code>station.manage</code>; a catalog publishing tool <code>catalog.publish</code>; an ad-hoc 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 ServerHello of connections to it.

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