Public reference
Auth
Every endpoint in this group. Open one for its parameters and a worked example.
Auth
24GET /api/v1/auth/account
- Authentication
- Staff token or session Staff session only — an API token cannot call this
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
PATCH /api/v1/auth/account
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/account/2fa/disable
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
account_reauth
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/account/2fa/enable
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/account/2fa/recovery-codes
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
account_reauth
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/account/2fa/setup
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/account/avatar
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
GET /api/v1/auth/account/limits
- Authentication
- Staff token or session Staff session only — an API token cannot call this
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/account/password
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
account_reauth
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
GET /api/v1/auth/account/sessions
- Authentication
- Staff token or session Staff session only — an API token cannot call this
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/account/sessions/revoke-others
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
DELETE /api/v1/auth/account/sessions/{jti}
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
GET /api/v1/auth/context Classify the host before signing in
Tells a login page which flow to render: whether the host it was loaded on is a tenant subdomain, the instance apex, or unknown, plus the public tenant descriptor when it resolves. Unauthenticated, and always 200. It exposes only the public tenant slug, name and branding, and tenant is null for apex and unknown hosts.
- Authentication
- Public
POST /api/v1/auth/impersonation/exit
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/login Sign a manager in
Exchanges an email or username and a password for a tenant-scoped session token. The tenant is taken from the host when you call a tenant subdomain, and a selector in the body is discarded in that case.
- Authentication
- Public
- Rate limit
login
mfa_required is a 401 with the same code as a wrong password. Branch on details.reason, never on the status or the message: six different login outcomes share ERR_UNAUTHORIZED and only the reason tells them apart. expires_at is unix SECONDS, not milliseconds and not a formatted timestamp.
Parameters
| Parameter | Description |
|---|---|
emailrequired
body · string
|
Email or username. |
passwordrequired
body · string
|
The manager's password. |
totp_code
body · string
|
Six-digit code or a recovery code. Sent on the second attempt, after the first returns mfa_required. |
tenant_slug
body · string
|
Honoured only when the host carries no tenant. Ignored outright on a tenant subdomain. |
refresh
body · boolean
|
Opt in to the refresh-token flow. Omitting it returns one long-lived token and no refresh fields at all. |
{
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"user_id": 41,
"tenant_id": 12,
"tenant_slug": "acme",
"roles": ["support"],
"expires_at": 1758358800
}
}POST /api/v1/auth/logout End the current session
Revokes the calling session's token id, so it stops working immediately rather than at expiry.
- Authentication
- Staff token or session Staff session only — an API token cannot call this
Best-effort by design: it answers ok even if the revocation write failed, because the worst case is a token that dies at its natural expiry. Do not treat ok true as proof the token is dead.
{
"data": { "ok": true }
}GET /api/v1/auth/me Who am I, and what may I do
The one-shot bootstrap call: the current manager, their roles, the resolved permission codes, and the tenant settings a client needs before it can render anything. Authenticated but not permission-gated, so any working credential reaches it.
- Authentication
- Staff token or session
For an API token, permissions is the INTERSECTION of the token's scope with its owner's live permissions, and is_admin is forced to false even when the owner is a tenant administrator. That is the authoritative answer to what the credential may do — gate your client on this array, not on the owner's role names. max_users null means unlimited; 0 means blocked, not unlimited.
{
"data": {
"version": "0.2.34",
"manager": {
"id": 41,
"tenant_id": 12,
"email": "ops@acme.example",
"username": "ops",
"status": "active",
"two_factor_enabled": true
},
"roles": ["support"],
"permissions": ["prm_users_index", "prm_users_update"],
"is_admin": false,
"settings": {
"currency": "EGP",
"timezone": "Africa/Cairo",
"default_language": "en",
"pos_undo_window_seconds": 60
},
"tenant": {
"license_status": "active",
"license_expires_at": "2027-01-31 00:00:00",
"max_users": 5000,
"users_count": 812,
"blocked": false,
"blocked_reason": ""
}
}
}DELETE /api/v1/auth/push-tokens
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/push-tokens
- Authentication
- Staff token or session Staff session only — an API token cannot call this
- Rate limit
t_mutate
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/refresh Exchange a refresh token
Issues a new session token from a refresh token. Only available when the original login asked for one.
- Authentication
- Public
- Rate limit
refresh
An expired refresh token and an unknown one answer identically, on purpose. A revoked session is the one case that is distinguished, because the remedy differs: sign in again rather than retry.
Parameters
| Parameter | Description |
|---|---|
refresh_tokenrequired
body · string
|
The refresh token returned by login. Shown once; only its hash is stored. |
POST /api/v1/auth/register/complete
- Authentication
- Public
- Rate limit
register_complete
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/register/resend
- Authentication
- Public
- Rate limit
register_resend
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/register/start
- Authentication
- Public
- Rate limit
register_start
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
POST /api/v1/auth/register/verify
- Authentication
- Public
- Rate limit
register_verify
Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.
No endpoint matches that search.
Written to be read by machines too
The reference is public and needs no account, so a tool that has never seen X-Radius can reach a correct first call on its own.
- /llms.txt
- An index of every page, with one-line summaries.
- /llms-full.txt
- The whole reference as one Markdown file, with no navigation to crawl.
- /openapi.json
- OpenAPI 3.1, generated from the router that serves this instance.
- /skill.md
- A ready-made skill file for an assistant: authentication, the response envelope and the error codes in one page.
<page-url>.md- Append .md to any reference URL for the same page as Markdown.
Accept: text/markdown- Send this header on the ordinary URL and the answer comes back as Markdown instead.
Read https://x-radius.com/llms.txt, then fetch the endpoint you need as Markdown by appending .md to its URL.