Documentation

Everything you need to know about Auth.io

Explore every screen, understand each flow, and learn how all the pieces connect — from creating your first realm to issuing tokens in production.

Live preview · mock data
authio.web.hyperio.tech/dashboard

Welcome back!

Track activity across your realms, clients and users at a glance.

Realms

12

9 active · +3 this week

Clients

38

34 active · 29 PKCE

Users

8.4K

across all realms

Sessions

126K

$114 est. cost

Distribution by Realm

Realm Status

12realms
Active
975%
Inactive
325%

Recent Realms

View all

acme-prod

12 clients · 128 users · created 2 months ago

partner-hub

7 clients · 64 users · created 3 weeks ago

mobile-apps

5 clients · 41 users · created 5 days ago

Platform architecture

How entities connect in Auth.io

01

Realm

Tenant boundary

02

Client

App registration

03

Users / Consumers

Identities & APIs

04

Roles & Scopes

Authorization

05

Keys & Secrets

Security layer

Platform screens

Every screen explained

Every entity in the platform — what it's for, how it's configured, and how it connects to the rest of Auth.io.

01

Realms

Multi-tenant isolation

A Realm is the top-level tenant boundary. It isolates users, clients, scopes, roles, keys, and all configurations. Everything starts with creating a realm.

Key features

Complete environment isolation per realm
Each realm has its own identity domain and policies
Realm-level statistics: total clients, total users
Enable or disable realms with status control
Define realm description and organizational context
Pro tip

Create separate realms for development, staging, and production environments to maintain complete isolation.

authio.web.hyperio.tech/dashboard

Welcome back!

Track activity across your realms, clients and users at a glance.

Realms

12

9 active · +3 this week

Clients

38

34 active · 29 PKCE

Users

8.4K

across all realms

Sessions

126K

$114 est. cost

Distribution by Realm

Realm Status

12realms
Active
975%
Inactive
325%

Recent Realms

View all

acme-prod

12 clients · 128 users · created 2 months ago

partner-hub

7 clients · 64 users · created 3 weeks ago

mobile-apps

5 clients · 41 users · created 5 days ago

Connections

Clients belong to a realm
Users are scoped within a realm's client
Scopes and roles can be global or realm-specific

Fields

NameRealm ID (slug)DescriptionStatus (Active / Inactive)
02

Clients

Application registration

Clients represent the applications that participate in OAuth2 and OIDC flows. Each client has its own configuration for identity, tokens, login branding, and email.

Key features

Grant types: Authorization Code, Client Credentials, Refresh Token, Device Code, Password, Personal Access Token
PKCE, on by default — allow S256 rather than plain, which sends the verifier in the clear
One registered redirect URI per client; a second environment needs its own client
Token configuration: JWS/JWE algorithms, lifetimes, audience
Login page branding: colors, logo, title, background
Email configuration: SendGrid integration for verification
Identity policies: password rules, lockout, username validation
Pro tip

Use Authorization Code + PKCE for public apps (SPA/mobile) and Client Credentials for server-to-server integrations.

authio.web.hyperio.tech/security/api-secret

API Secrets

Scoped machine credentials with expiry and usage tracking.

New secret

Active secrets

3 secrets

production-api

sk_live_9f2a••••••••••••
Expires Dec 2026
used 4 min ago

ci-pipeline

sk_live_c7d1••••••••••••
Expires Oct 2026
used 1 hour ago

legacy-integration

sk_live_04be••••••••••••
Expires in 12 days
used 2 days ago

Client Authentication

PKCE required
S256
Client secret
Enforced
Lockout policy5 attempts / 15 min

Token Configuration

Issuer

https://auth.authio.com/realms/acme-prod

Audience

api://acme-platform
Access token TTL3600s

Connections

Belongs to a realm
Contains users and consumers
Has allowed scopes and grant types
Keys are issued per client context

Fields

Client IDNameDescriptionStatusGrant TypesPKCE MethodsScopesRedirect URI
03

Users

Identity management

Users are human identities that authenticate through interactive login flows. They have credentials, roles, sessions, and follow the client's identity policies.

Key features

Passkeys (WebAuthn) registered per device, listed and revocable
Full user lifecycle: create, activate, deactivate
Username, email, first name, last name, phone number
Password governed by client identity policies
Role assignment per user (multiple roles supported)
Token history and active session tracking
Email verification support
Lockout policies based on failed attempts
Pro tip

Users authenticate via the hosted login page. Their permissions come from the combination of assigned roles and their scopes.

authio.web.hyperio.tech/users

User Management

Search, inspect and manage identities across every realm.

Add user
Total users

8,412

all realms

Active

8,020

95% verified

Users

View all
SA

Sofia Almeida

sofia@acme.io

Active
last login 2 min ago
MR

Marcos Ribeiro

marcos@acme.io

Active
last login 15 min ago
JC

Julia Castro

julia@partner.co

Pending
last login never
DS

Daniel Souza

daniel@acme.io

Active
last login 1 hour ago

Connections

Belongs to a client within a realm
Has assigned roles with scopes
Generates tokens and sessions
Subject to identity policies of the client

Fields

UsernameEmailFirst NameLast NamePhoneStatusRoles
04

Consumers

API & integration credentials

Consumers represent non-interactive (machine-to-machine) integrations. They are credentials bound to a client with their own scopes and roles for API access.

Key features

Bound to a specific client
Consumer types for different integration patterns
Own set of allowed scopes and roles
Masked secret value for security
Granular access control per consumer
Status management: activate or deactivate
Pro tip

Use consumers for backend services, cron jobs, and third-party integrations that need API access without user interaction.

Connections

Belongs to a client
Has dedicated scopes and roles
Uses Client Credentials flow
Independent from user sessions

Fields

NameDescriptionTypeValue / SecretStatusScopesRoles
05

Roles & Scopes

Authorization model

Roles group permissions, and scopes define what actions or resources are accessible. Together they form the authorization model for users, consumers, and API calls.

Key features

Global roles shared across the platform
Custom roles per realm or client
OIDC standard scopes: openid, profile, email, address, phone
Custom scopes for fine-grained API permissions
Role-to-scope mapping for structured access
Assign roles to users and consumers independently
Pro tip

Start with OIDC standard scopes, then add custom scopes as your API grows. Map scopes to roles for clean authorization.

Connections

Scopes are allowed at client level
Roles contain scopes as claims
Users and consumers receive roles
Token claims reflect assigned roles and scopes

Fields

Role NameRole StatusScope NameScope Type (Global / Custom)Role-Scope Mapping
06

Keys & Secrets

Cryptography & security

Keys handle signing and encryption of tokens (JWS/JWE). Secrets include client secrets, API keys, encryption keys, and other credentials needed for security operations.

Key features

Signing keys for token integrity (JWS)
Encryption keys for token confidentiality (JWE)
Multiple secret types: API Key, Client Secret, Signing Key, Encryption Key, Webhook Secret
Expiration tracking and rotation support
Key algorithm configuration per client
JWKS endpoint exposure for public key distribution
Pro tip

Rotate keys regularly and use different algorithms (RS256, ES256) based on your security requirements.

authio.web.hyperio.tech/keys

Security Keys

Signing and encryption key material per client, with rotation.

Rotate keys
Active keys

3

in rotation

Current

1

signing tokens now

RS256

Current

RSA Key · SIG

Active
8f2c1a9e-77b4-4f10-9d3a-2b6f0c4e8a51

Created Jun 12, 2026

ES256

EC Key · SIG

Active
c41d7b02-3e88-45c6-b7f9-91a2d5e6c3f0

Created May 30, 2026

RS256

RSA Key · ENC

Active
a93f5e17-6c02-49d8-8b41-f07c3a9d2e64

Created May 02, 2026

RS256

RSA Key · SIG

Revoked
5d80b6c3-19af-4e72-a0c5-84e1f2b7d9a3

Created Feb 18, 2026

Connections

Token configuration uses signing and encryption keys
Client Secret is used in Client Credentials flow
JWKS endpoint allows resource servers to verify tokens
Key rotation policy is per client

Fields

Key TypeAlgorithmNameValueExpirationAssociated ScopesAssociated Roles
07

Security

Dashboard & monitoring

The security dashboard provides visibility into active sessions, token usage, key status, and overall security posture of the environment.

Key features

Active session monitoring per user
Token issuance and usage statistics
Key expiration alerts
Security posture overview
Audit trail for authentication events
Passkeys registered per user, revocable from here
Pro tip

Review the security dashboard regularly to detect anomalies, expired keys, and unusual session patterns.

authio.web.hyperio.tech/dashboard

Audit & Access Intelligence

4,531 events recorded
Total Events

4,531

access events recorded

Successful

4,369

authentications passed

Failed

162

access attempts blocked

Success Rate

96%

Excellent

Recent Access Events

acme-prod

Password Login

2 min ago

Success
Sofia Almeida
187.44.120.8Chrome 126Windows 11
Jul 26, 10:42 AM
View details

Client Credentials

8 min ago

Success
billing-service
34.201.10.77
Jul 26, 10:36 AM
View details

Token Refresh

15 min ago

Success
Marcos Ribeiro
52.67.190.14Safari 17macOS 15
Jul 26, 10:29 AM
View details

Password Login

23 min ago

Failed
unknown@mail.com
191.36.8.201Firefox 128Ubuntu 24.04

Invalid credentials — account locked after 5 attempts

Jul 26, 10:21 AM
View details

Connections

Monitors all users and consumers
Tracks tokens issued by clients
Alerts on key and secret expiration
Provides governance insights per realm

Fields

Active SessionsToken StatisticsKey StatusSecurity Alerts
08

Settings

Account & configuration

The settings area manages your account profile, notification preferences, account security, and subscription management.

Key features

Profile management: name, email, avatar
Notification preferences
Account security: password change, 2FA
Subscription management and billing
Usage tracking and plan limits
Pro tip

Keep your subscription active and monitor usage to avoid rate limiting or feature restrictions.

Connections

Controls billing through Stripe integration
Manages account-level security
Subscription determines available features and limits

Fields

ProfileNotificationsSecuritySubscription
Setup journey

From zero to the first issued token

Follow the recommended implementation order. Click each step to see details and the corresponding API call.

Create your Realm

Define the main environment for your application. The realm establishes tenant isolation, naming, and organizational context.

Checklist

Choose a unique realm identifier (slug)
Add a description for organizational clarity
The realm becomes your tenant boundary

API example

POST/api/v1/admin/realms
{
  "name": "My Application",
  "realmId": "my-app",
  "description": "Production environment"
}
Authentication flows

Every flow, end to end

Pick a flow to read what each step actually does and see the request that drives it. Every URL below is a real Auth.io endpoint — only the issuer is a placeholder.

Authorization Code + PKCE

Web apps, SPAs and mobile apps — anything with a person in front of it. PKCE is on by default for new clients.

1
Initiate
Your app generates a code_verifier, derives an S256 code_challenge from it, and redirects the browser to the authorization endpoint.
2
Authenticate
The user signs in on the hosted login page for that realm and client, following the login flows configured on it.
3
Consent
Scopes are resolved against what the client is allowed. Anything not allowed is dropped rather than granted.
4
Callback
Authio redirects back to the registered redirect_uri with a single-use authorization code that expires in 30 seconds.
5
Exchange
Your app posts the code and the original code_verifier to the token endpoint and receives access_token and id_token — plus refresh_token when offline_access was granted.
6
Access
Send the access_token as a bearer token. The id_token describes the user; it is not a credential for your API.

Code example

// 1. Send the browser to the authorization endpoint.
const params = new URLSearchParams({
  response_type: 'code',
  client_id: 'web-app',
  redirect_uri: 'https://app.example.com/api/auth/callback/authio',
  // offline_access is what buys a refresh_token — nothing else does.
  scope: 'openid profile email offline_access',
  code_challenge: codeChallenge,
  // Always send this. The authorization endpoint accepts a challenge
  // without a method, and the exchange then fails at the token
  // endpoint — a long way from the request that caused it.
  code_challenge_method: 'S256',
  state: randomState,
})

window.location.href =
  'https://auth.example.com/realms/acme/protocol/openid-connect/auth?' + params

// 2. Exchange the code for tokens, from your server.
const tokens = await fetch(
  'https://auth.example.com/realms/acme/protocol/openid-connect/token',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: authorizationCode,
      // Byte-for-byte the redirect_uri sent in step 1.
      redirect_uri: 'https://app.example.com/api/auth/callback/authio',
      client_id: 'web-app',
      code_verifier: codeVerifier,
    }),
  },
)
Integration examples

Ready-to-use code snippets

The Next.js examples use authio-provider-nextauth, the first-party provider package — one entry point per NextAuth major, with the Authio defaults already set. Inside the console, each client's Integration guide prints these same recipes with its own values filled in.

TypeScript
// npm install next-auth@5.0.0-beta.32 authio-provider-nextauth@^2

// .env.local — Auth.js resolves these three from the provider id, "authio".
//   AUTH_AUTHIO_ISSUER="https://auth.example.com/realms/acme"
//   AUTH_AUTHIO_ID="web-app"
//   AUTH_AUTHIO_SECRET="…"        omit entirely for a public client
//   AUTH_URL="https://app.example.com"
//   AUTH_SECRET="…"               npx auth secret — NOT the client secret

// auth.ts
import NextAuth from 'next-auth'
import { Authio } from 'authio-provider-nextauth/v5'

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    Authio({
      // The v5 entry point sets no checks of its own, so Auth.js would
      // default to ['pkce'] alone. 'state' ties the callback to the
      // request that started it.
      checks: ['pkce', 'state'],
      // offline_access is what buys a refresh token. Nothing else does.
      authorization: {
        params: { scope: 'openid profile email offline_access' },
      },
    }),
  ],
  session: { strategy: 'jwt' },
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token
        token.refreshToken = account.refresh_token
      }
      return token
    },
    async session({ session, token }) {
      session.accessToken = token.accessToken as string
      return session
    },
  },
})

// app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/auth'
export const { GET, POST } = handlers

// Register this exact callback on the client:
//   https://app.example.com/api/auth/callback/authio
Ongoing operations

Beyond setup: governing the environment

Authentication is just the beginning. These areas require ongoing attention to maintain security and compliance.

Login branding

Customize the hosted login page: title, subtitle, colors, logo, background, and behavior per client.

Identity policies

Control password rules, username validation, lockout thresholds, email verification, and sender configuration.

Token & encryption

Configure JWS/JWE algorithms, token lifetimes, audience, key rotation, and signing strategies per client.

Observability

Monitor active sessions, consumer usage, client status, secret expiration, and security posture.

Frequently asked questions

Common questions answered

Users are human identities that authenticate through interactive login (Authorization Code flow). Consumers are machine credentials used for server-to-server API access (Client Credentials flow). Both can have roles and scopes, but they operate through different authentication patterns.
Ready to build?

Start building your authentication layer today

You now understand the full platform: realms, clients, users, consumers, roles, scopes, keys, and all authentication flows. Time to bring it to life.