Core concepts
The objects you work with in Authio — accounts, realms, clients, users, roles, scopes, consumers, organizations, resource servers and sessions — and how they fit together.
Everything you configure in Authio hangs off a small set of objects. Your account owns one or more realms. Each realm is an identity provider of its own, with its own users, applications and keys. Inside a realm, clients sign people in and request tokens, and resource servers are the APIs those tokens are for.
This page explains each object in a few paragraphs and points to the page that covers it in depth. If you have not created anything yet, the Quickstart walks you through your first realm and client.
How they relate
Account
├── Team: owner, admins, developers, auditors
├── API secrets
├── Roles and scopes
└── Realm acme (issuer https://authio.api.hyperio.tech/realms/acme)
├── Users
├── Organizations
├── Resource servers
└── Client acme-web
├── Consumers
└── Groups| Object | Belongs to | What it is for |
|---|---|---|
| Account | — | Your company on Authio: the subscription, the team that runs the console, and everything below. |
| Realm | Account | An isolated tenant with its own issuer, keys, users, clients and policies. |
| Client | Realm | An application that signs people in or requests tokens. |
| User | Realm | A person who signs in. One user per person per realm. |
| Consumer | Client | A machine identity with its own credential, scopes and roles. |
| Role | Account, optionally limited to one realm, client, user or group | A named set of claims carried in the tokens of whoever holds it. |
| Scope | Account, optionally limited to one realm or client | The name of a permission an application asks for. |
| Organization | Realm | One of your business customers, with its members and domains. |
| Resource server | Realm | An API or MCP server that tokens are issued for. |
| Session | User and client | The record of a sign-in, cited by every token issued from it. |
Account
The account is your company on Authio. It holds the subscription, the team that signs in to the console, the API secrets your automation uses, the roles and scopes you define, and every realm you create. Records belong to the account rather than to the person who created them, so nothing is lost when someone leaves the team.
Each team member holds one of four account roles — Owner, Admin, Developer or Auditor — that decide what they can see and change. Team and access covers the roles and invitations, and Plans and billing covers the subscription.
Realm
A realm is an isolated tenant and a complete identity provider. It has its own issuer, discovery document and public keys, its own users, clients and sessions, and its own password and lockout policy. A token issued in one realm is never accepted in another, which makes the realm the boundary to draw between environments, such as production and staging, or between products that must not share users.
The realm ID is part of every address the realm publishes. It is 3 to 64 characters of lowercase letters, digits and hyphens, unique across Authio, and cannot be changed once the realm exists.
Issuer https://authio.api.hyperio.tech/realms/acme
Discovery https://authio.api.hyperio.tech/realms/acme/.well-known/openid-configuration
JWKS https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/certsSigning keys are generated per client and published together in the realm’s JWKS, so an API verifies any token of the realm against one key set. Keys rotate automatically, every 90 days by default, and a replaced key stays published until the last token it signed has expired. You can follow and rotate them under Signing Keys.
Client
A client is an application registered in a realm: a web app, a single-page app, a mobile or desktop app, a CLI, a back-end service or an AI agent. Its client ID — lowercase letters, digits and hyphens, up to 100 characters — is what the application sends to Authio, and its display name is what people see on the sign-in screen.
| Type | Secret | Token endpoint authentication | Typical use |
|---|---|---|---|
| Confidential | Yes, generated by Authio and shown only when created or rotated | client_secret_basic (default) or client_secret_post | Server-rendered web apps, back ends and services |
| Public | No | none, and PKCE with S256 is required | Single-page apps, mobile and desktop apps, CLIs |
Each client also decides, independently of the other clients of its realm:
- Its redirect URIs: the only addresses Authio sends a person back to after sign-in, compared in full.
- Its grant types: the ways it may request a token. PKCE is required by default for the authorization code flow.
- Its sign-in steps: password, one-time code, passkey or push approval, and whether each one is required.
- Who may sign in: by default only users linked to the client, such as the ones created through it or granted access to it. Turning this off lets any user of the realm in.
- Its token settings: lifetimes, format, signing algorithm and how often its keys rotate.
Authio supports seven grant types, each switched on per client:
| Grant | grant_type | Used for |
|---|---|---|
| Authorization code | authorization_code | Apps that sign a person in through the browser |
| Refresh token | refresh_token | Renewing tokens without a new sign-in |
| Client credentials | client_credentials | Services calling APIs as themselves |
| Device code | urn:ietf:params:oauth:grant-type:device_code | TVs, CLIs and devices without a browser |
| Token exchange | urn:ietf:params:oauth:grant-type:token-exchange | Acting on a person’s behalf, and connected accounts |
| Password | password | Legacy integrations that cannot open a browser |
| Personal access token | personal_access_token | Scripts and pipelines using a pre-generated key |
User
A user is a person who signs in to a realm. Each person has one user per realm — one username, one password, one set of passkeys and second factors — shared by every client of that realm. The realm’s password and lockout policy applies to all of them, while each client decides which sign-in steps to ask for.
Users are created by an administrator in Users or through the Admin API, on their first sign-in through an external identity provider, or by importing them from another provider. Users of different realms are unrelated, even when they share an email address.
Console users and realm users
The people on your team are users too, but of a different realm: the console signs in through the hosted login of Authio’s own realm, like any other application. A console user is never a user of your realms, so signing in to the console as ana@acme.com and signing in to your app as ana@acme.com are two separate users with separate credentials. Each console user belongs to at most one Authio account.
Roles and scopes
A role says what someone is. It is a named set of claims, defined in your account, that Authio writes into the tokens of whoever holds it. A role reaches a user in one of four ways: assigned to them directly, through a group they belong to, granted by a client to everyone who signs in through it, or granted by a realm to everyone in it. Consumers hold roles too.
A scope says what an application may ask for. Clients request scopes at sign-in, both the OpenID Connect ones such as openid, profile, email and offline_access and your own, such as orders:read. For each client, a scope is either default, always granted, or optional, granted when the client asks for it. The user’s roles appear in the access token when the roles scope is granted.
A role or a scope can be global to the account or exclusive to one realm or client (a role also to one user or group), which limits where it can ever be assigned. A group is a named set of users of one client that passes its roles to every member. Roles and permissions and Scopes and claims cover both in depth.
Consumers
A consumer is a machine identity attached to a client: a back-end service, a partner integration or a scheduled job that authenticates as itself rather than on behalf of a person. Each consumer has its own credential — a secret for the client credentials grant, an API key or a personal access token — and its own scopes and roles.
A client that serves several integrations gives each one its own consumer instead of sharing a single secret among them, so one integration can be suspended or rotated without touching the others. See Machine-to-machine.
Organizations
An organization is one of your business customers, represented inside a realm. It has its own members, email domains proven with a DNS TXT record, identity providers and sign-in branding, so a B2B product serves every customer from one realm instead of creating a realm for each.
An application asks for one organization’s sign-in by sending its alias in the organization parameter of the authorization request, and the tokens carry the organization the person signed in under as org_id and org_alias. Membership does not grant roles by itself: roles still come from assignments, groups and grants. See Organizations.
Resource servers
A resource server is an API, often an MCP server, registered in a realm. Its identifier is an absolute URI that becomes the audience (aud) of the tokens issued for it, so the API can refuse tokens meant for anything else. It declares its own scopes, lists the clients allowed to request tokens for it, and names a confidential client it uses to introspect them.
A client asks for a token for a resource server by sending its identifier in the resource parameter (RFC 8707). Resource servers are part of the MCP integration capability of your plan. See Resource servers.
Sessions
Signing in opens a session for that person in that client, and every token issued from it carries the session ID in the sid claim. Ending the session — the person signs out, an administrator revokes it, or the user is suspended — stops those tokens from being renewed and makes introspection report them as inactive. A session lasts 10 hours by default, configurable per client.
Single sign-on is opt-in per client and off by default. Clients that take part share the realm’s sign-in: someone signed in to one of them enters the others without typing credentials again, as long as nothing has changed. A new password, a suspension or a sign-in step the next client requires sends them back to the sign-in screen. See Sessions and single sign-on.