Complete Platform Guide

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.

Explore screensAuthentication flows

Platform Architecture

How entities connect in Auth.io

RealmTenant boundary
ClientApp registration
Users / ConsumersIdentities & APIs
Roles & ScopesAuthorization
Keys & SecretsSecurity layer
Platform Screens

Every screen explained in detail

Click on any entity below to explore its purpose, features, data model, and how it connects to the rest of the platform.

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.

Connections

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

Fields & Data

NameRealm ID (slug)DescriptionStatus (Active / Inactive)
Realms
Navigate to: /realms
Name
Realm ID (slug)
Description
Status (Active / Inactive)
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/admin/realms
{
  "name": "My Application",
  "realmId": "my-app",
  "description": "Production environment"
}
Authentication Flows

Four flows for every integration pattern

Auth.io supports the most important OAuth2 and OIDC flows. Select a flow to understand each step and see a code example.

Authorization Code + PKCE

Recommended

Use case

SPAs, mobile apps, and any public client that needs interactive login with maximum security.

1
Initiate
Your app generates a code_verifier and code_challenge, then redirects the user to the Auth.io authorization endpoint.
2
Authenticate
The user authenticates on the Auth.io hosted login page with their credentials.
3
Consent
Scopes are evaluated. If consent is required, the user approves the requested permissions.
4
Callback
Auth.io redirects back to your app with an authorization code in the URL.
5
Exchange
Your app exchanges the code + code_verifier for access_token, refresh_token, and id_token.
6
Access
Use the access_token to call protected APIs. The id_token contains user identity claims.

Code Example

Click "Show" to reveal the code example

Integration Examples

Ready-to-use code snippets

Copy and adapt these examples to integrate Auth.io into your application.

TypeScript
import NextAuth from 'next-auth'

export default NextAuth({
  providers: [{
    id: 'authio',
    name: 'Auth.io',
    type: 'oauth',
    wellKnown: `${process.env.AUTHIO_URL}/realms/${realm}/.well-known/openid-configuration`,
    clientId: process.env.AUTHIO_CLIENT_ID,
    clientSecret: process.env.AUTHIO_CLIENT_SECRET,
    authorization: { params: { scope: 'openid profile email' } },
    idToken: true,
    profile(profile) {
      return {
        id: profile.sub,
        name: profile.name,
        email: profile.email,
      }
    },
  }],
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token
        token.refreshToken = account.refresh_token
      }
      return token
    },
  },
})
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 environment security posture.

Frequently Asked Questions

Common questions answered

Ready to build?

Start building your authentication layer today.

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

Create free accountBack to home

Realm ready

Multi-tenant environment isolated

Client active

OAuth2 flows and tokens configured

Identities created

Users and consumers provisioned

Security validated

Keys, scopes, and policies live