SimTX API v24/Permissions - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:27:17Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:27, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{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/Packets/HandshakeResult\|HandshakeResult]].		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 ==		== Boolean permissions ==
Line 8:		Line 8:
	! Identifier !! Grants !! Relevant to		! Identifier !! Grants !! Relevant to
	\|-		\|-
	\| <code>game.transmit</code> \|\| Opening transmitter sessions (roles 2 and 3). \|\| [[SimTX API/Transmitter session]]		\| <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/Extension catalog protocol]]		\| <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/Packets/TxQueue\|TxQueue]]		\| <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/Packets/TransmitterSessionRequest\|TransmitterSessionRequest]]		\| <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/Moderation session]]		\| <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/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/Packets/ForwardedClientAddress\|ForwardedClientAddress]] on behalf of proxied receivers. \|\| [[SimTX API/Receiver 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. \|\|		\| <code>accounts.admin</code>, <code>awards.manage</code> \|\| Administration of the account service. Not used by game servers. \|\|
Line 42:		Line 42:
	\|}		\|}

	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/Limits and errors]].		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.		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 ==		== 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. 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.		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.		* An empty scope at device login means every permission the account held when the user approved the login.
Line 56:		Line 56:
	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.		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 navbox}}		{{SimTX API v24 navbox}}
	[[Category:SimTX API]]		[[Category:SimTX API v24]]
	[[Category:SimTX API account service]]		[[Category:SimTX API v24 account service]]

Clanker: Clanker moved page SimTX API/Permissions to SimTX API v24/Permissions: Archive the v24 protocol reference

2026-10-24T16:21:08Z

Clanker moved page SimTX API/Permissions to SimTX API v24/Permissions: Archive the v24 protocol reference

← Older revision	Revision as of 16:21, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:54:53Z

SimTX API documentation

New page

{{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/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/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/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/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/TransmitterSessionRequest|TransmitterSessionRequest]]
|-
| <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, stations 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 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/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/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 navbox}}
[[Category:SimTX API]]
[[Category:SimTX API account service]]