API tokens

An API token lets another system call the X-Radius API on a manager's behalf, without putting that person's password in a configuration file and without giving the script their entire authority.

What a token is

A token belongs to exactly one manager and is created under Developer → API Tokens. It starts with xrt_, which nothing else in the system emits, so it is easy to find in a leaked configuration or a secret scanner.

Treat it exactly like a password. Anyone holding it can act as its owner, within the token's access, until it is revoked.

The base URL

https://<your-tenant-slug>.<instance-domain>/api/v1

Use the host you see in the browser when you are signed in to the panel. The API Reference page inside the panel prints your exact base URL for this reason.

Calling the instance's own address instead resolves no tenant, so every request comes back empty or unauthorised — and it looks exactly like a bad token. If your first call fails, check the host before anything else.

Authentication and responses

Send the token on every request. There is no sign-in step and no session to refresh.

curl -s https://acme.example.com/api/v1/auth/me \
  -H "Authorization: Bearer $XRADIUS_TOKEN"

/auth/me returns who the token acts as and the exact list of permissions it holds. If that call succeeds, the rest is a matter of picking endpoints.

Success wraps the payload in data, and a list adds a meta block with paging:

{ "data": [], "meta": { "page": 1, "page_size": 25, "total": 812 } }

Errors always use one shape, with a code, a human message, a request_id to quote when asking for help, and a machine-readable details.reason. Timestamps on the wire are yyyy-MM-dd HH:mm:ss in UTC.

What a token may do

A token's access is recomputed on every request as the owner's permissions right now, intersected with the token's scope. Three consequences:

• A token can never do more than its owner. Ticking a permission you do not hold has no effect: a scope is a ceiling, not a grant.
• It tracks its owner live, in both directions. Demote the owner and the token shrinks the same second.
• A restricted token is restricted even for an administrator. A token scoped to "view subscribers" is not an admin token, whoever created it.

Choose full access when the integration is genuinely you-in-a-script. Choose restricted, with the smallest set that works, for anything else.

What a token may never do

Some surfaces refuse tokens outright:

• Account credentials — password, two-factor, sessions. A token that could change its owner's password would be an account-takeover primitive.
• Token management itself. Otherwise a token could widen its own scope.
• Signing in as another manager, which would let a token hop to a more powerful account.

Signing in as a subscriber is allowed, because it goes the other way: a subscriber can do strictly less than the manager who authorised it. The borrowed session is capped at an hour, gets no refresh, and everything done inside it is logged against the token's owner.

Managing tokens

Show displays the secret again and asks for your password; it is written to the audit log. Roll issues a new secret immediately and kills the old one with no overlap, because the case that matters is a leak. Disable is a reversible off switch. Revoke is permanent, and the record stays in the list so you can see what the token did.

For planned rotation, create a second token, move the integration over, confirm it works, then revoke the first. Rolling is the emergency path.

If it did not work

• Everything returns empty or unauthorised. You are calling the instance's address instead of your tenant's.
• insufficient_permissions on an endpoint you expected to work. Widen the token's scope — or check the owner holds that permission at all, since the scope cannot exceed them.
• api_token_forbidden. That endpoint refuses tokens by design; do it as a signed-in person.