Documentation

Getting Started

Authagonal gives each tenant a fully standards-compliant OIDC server. Every tenant gets its own issuer URL, discovery document, and token endpoints — no shared infrastructure between tenants. You can go from zero to a working login flow in under 5 minutes.

Create an Account

Sign up at authagonal.io and choose a slug for your account. The slug becomes your issuer domain: {slug}.authagonal.io. After creating your account, verify your email address to get started.

Choose a unique slug for your account during signup

Register a Client

Navigate to Clients in the portal sidebar and click Create. Enter a clientId and clientName for your application. Then configure at least one redirect URI — this is where users are sent after authenticating. For example: https://app.example.com/callback.

Register a new OAuth client in the portal

Your First Login

The fastest way to integrate is with oidc-client-ts, a lightweight OIDC client library for JavaScript and TypeScript applications.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

If you prefer a minimal approach without a library, you can use the standard OAuth 2.0 authorization code flow with plain fetch:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

The default login page for your tenant

Dashboard

The portal dashboard gives you a real-time overview of your tenant. It surfaces the metrics that matter most — user growth, authentication activity, and quick navigation to every feature in the portal.

Overview

At the top of the dashboard you will see a welcome message along with your current total user count. Below that, a Daily Active Users chart displays a 7-day history of unique users who authenticated each day, giving you a quick pulse on engagement trends.

The dashboard home screen with DAU chart and activity overview

Activity Metrics

The activity metrics panel displays four stat cards summarizing key authentication events:

• Successful Logins — total completed authentication flows
• Failed Logins — incorrect credentials, locked accounts, or policy rejections
• Active Users — unique users who authenticated in the selected period
• SCIM Operations — user and group provisioning events from connected IdPs

Use the time range filters to switch between 24 hours, 3 days, 7 days, and 30 days. All stat cards and charts update to reflect the selected window.

Activity metrics with configurable time range

Quick Navigation

Below the metrics panel, navigation cards link directly to every major feature: Clients, Users, Groups, Roles, SSO, SCIM, Branding, and Settings. Each card shows a brief description so new team members can orient themselves quickly.

Clients

OAuth clients represent the applications that authenticate users through your tenant. Each client has its own configuration for redirect URIs, scopes, grant types, token lifetimes, and MFA policy.

Client List

The Clients page displays a table of all registered clients. Each row shows the clientId, display name, allowed grant types as colored badges, and whether PKCE is enabled. Click any row to open the full configuration editor.

Client list with grant type badges and PKCE indicators

Creating a Client

Click Create Client to register a new application. You need to provide two fields:

• clientId — a unique identifier for the client (e.g. my-spa)
• clientName — a human-readable display name

Register a new OAuth client

Deleting a Client

To delete a client, open the client configuration and click the Delete Client button at the bottom of the page. You will be asked to confirm before the client is permanently removed. All active sessions and tokens for the deleted client are immediately invalidated.

Client Configuration Reference

Each client has a comprehensive set of configuration options organized into several sections.

General Settings

URIs

URI fields use a tag input — type a value and press Enter or comma to add it. Click the X on any tag to remove it.

Tag input fields for configuring URIs

Scopes & Grant Types

Token Lifetimes

Configure token lifetimes per client

Logout URIs

Clients can register both back-channel and front-channel logout URIs. Either or both are optional — configure whichever matches how your application clears its session.

MFA Policy

Each client can override the tenant-wide MFA policy with a per-client setting. The MFA policy dropdown offers three options:

Per-client MFA policy override

Enterprise SSO

Enterprise SSO lets your customers bring their own identity provider. Authagonal supports both SAML 2.0 and OIDC federation with domain-based routing, so users are automatically directed to the correct IdP based on their email address.

Domain-based SSO routing

SAML 2.0 Connections

To create a SAML connection, navigate to the SSO page and select the SAML tab. Provide the following:

When you save the connection, Authagonal fetches the metadata document and imports the IdP's signing certificate, SSO endpoint URL, and name identifier format. The metadata is periodically refreshed to pick up certificate rotations.

Create a SAML 2.0 SSO connection

OIDC Connections

To create an OIDC federation connection, select the OIDC tab and provide:

Create an OIDC federation connection

Domain Routing

Domain routing automatically redirects users to the correct identity provider based on their email domain. When a user enters their email on the login page, Authagonal checks if the domain portion (e.g. acme.com) matches any configured SSO connection. If it does, the user is seamlessly redirected to their organization's IdP.

Domain routing maps email domains to identity providers

JIT Provisioning

By default, when a user signs in via SSO for the first time and doesn't already exist in your tenant, Authagonal creates their account automatically (Just-In-Time provisioning). This can be disabled per connection by checking Disable JIT provisioning when creating or editing the connection.

When JIT provisioning is disabled, only users who have been pre-provisioned — via SCIM, the portal's Users page, or the API — can sign in through that connection. Unknown users receive an access_denied error and are directed to contact their administrator.

Users

The Users page lets you manage all end users in your tenant. You can search for users, view their details, create new accounts, and see how each user was provisioned.

Search & Pagination

The search bar supports filtering by email address or user ID. Search is debounced at 300ms so results update as you type without overwhelming the API. Results are paginated at 50 users per page — use the navigation controls at the bottom of the table to move between pages.

User Table

The user table displays the following columns for each user:

The user list with search bar and pagination

Creating Users

Click Create User to add a new local user. The form requires:

Create a new local user

User Detail

Click any row in the user list to open its detail page. From there you can edit profile data, manage roles, reset MFA, review custom attributes, and delete the user.

Profile

Edit email, first/last name, phone, company, external ID, and toggle the user's active flag. Email changes must remain unique across the tenant; the API returns email_in_use if taken.

Roles

Assign and unassign roles defined on the Roles page. Role membership is surfaced in ID and access tokens when the client has includeRolesInTokens enabled.

Multi-Factor Authentication

See every MFA credential registered for the user — authenticator app (TOTP), WebAuthn/passkeys, and recovery codes — each with its own registered/last-used timestamps. Remove individual credentials, or reset all MFA. Resetting forces the user to re-enroll at next login.

Custom Attributes

Arbitrary key/value data attached to the user. Keys must be unique. Attributes are exposed via the user profile API and SCIM, and can be mapped to access-token claims by configuring a custom scope's userClaims.

Delete User

Permanently removes the user and all their MFA credentials. Type the user's email to confirm — there is no undo.

Groups

Groups let you organize users and include group membership in tokens. Groups can be created manually in the portal or provisioned automatically via SCIM from an external identity provider.

Group List

The Groups page shows all groups in your tenant with the following information:

Group list with source indicators

Creating a Group

Click Create Group and enter a displayName for the group. Group names should be descriptive and unique within your tenant (e.g. "Engineering", "Billing Admins", "Beta Testers").

Group Detail & Members

Click any group to open the detail view. Here you can see all current members and manage membership:

• Add members — Enter a user ID to add a user to the group.
• Remove members — Click the remove button next to any member to remove them individually.

Manage group membership in the detail view

Groups in Tokens

When includeGroupsInTokens is enabled on a client, the ID token includes a groups claim containing the user's group memberships. Each entry includes the group id and name:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Roles

Roles support role-based access control (RBAC) in your application. Define roles in Authagonal, assign them to users, and use the roles claim in tokens to enforce authorization in your application logic.

Managing Roles

The Roles page displays a table of all defined roles with inline editing. Each role has:

Creating a Role

Click Create Role and provide a name and description. Role names should be concise and follow a consistent naming convention across your application (e.g. lowercase with hyphens: billing-admin).

Inline Editing

Roles support inline editing directly in the table. Click the pencil icon on any role to enter edit mode — the name and description fields become editable. Modify the values, then click the checkmark icon to save. Changes take effect immediately.

Deleting a Role

Click the delete icon on any role to remove it. You will be asked to confirm before the role is permanently deleted. Removing a role does not retroactively invalidate existing tokens — the role will be absent from new tokens issued after deletion.

Inline editing of roles in the roles table

Roles in Tokens

Roles assigned to a user are included as a roles claim in the ID token. Your application can read this claim to make authorization decisions:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "roles": ["admin", "billing-admin"]
}

SCIM Provisioning

SCIM 2.0 (System for Cross-domain Identity Management) enables automatic user and group provisioning from enterprise identity providers like Okta, Azure AD, OneLogin, and JumpCloud. When configured, user accounts and group memberships are automatically synced from the upstream IdP to your Authagonal tenant.

SCIM user lifecycle sync with downstream provisioning

Setup Steps

Follow these steps to enable SCIM provisioning for a client:

1. Select the client application — Choose the OAuth client that the SCIM provisioning will be associated with.
2. Generate a SCIM token — Provide a description and an expiry period in days, then generate the token.
3. Copy the token immediately — The raw token value is displayed only once. Copy it before closing the dialog.
4. Configure your IdP — In your identity provider's SCIM settings, enter the base URL and bearer token.
5. Test user sync — Trigger a test sync from your IdP and verify that users appear in the Authagonal portal.

SCIM Base URL

Configure your identity provider with the following base URL:

https://{slug}.authagonal.io/scim/v2

Replace {slug} with your tenant slug.

SCIM setup page with token generation

Token Management

SCIM tokens authenticate provisioning requests from your IdP. You can manage multiple tokens per client:

To revoke a token, click the Revoke button next to it. Revoked tokens remain visible in the list for audit purposes but immediately stop accepting requests.

Token management with active and revoked token indicators

Testing Connectivity

Verify that your SCIM integration is working by querying the ServiceProviderConfig endpoint:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

A successful response returns a JSON document describing the supported SCIM features, including bulk operations, filtering, and change password capability.

OAuth Scopes

Scopes let clients request specific slices of a user's data or permissions. Authagonal supports both standard OIDC scopes and custom scopes you define for your APIs.

Built-in Scopes

Custom Scopes

Define your own scopes on the Scopes page. Each scope describes a permission or resource a client can request (for example, billing.read, orders.write).

Custom claims on tokens

Custom claims have two halves. The source is per-user data: each AuthUser has a customAttributes dictionary you can populate from the Portal (Users → user → Custom Attributes), via SCIM, or via a TCC provisioning hook. The release is per-scope: each scope's userClaims list names the keys it permits to leave the server.

When a client requests scopes, Authagonal walks the granted scopes, unions their userClaims lists, and emits only those keys from the user's customAttributes. Unknown keys are silently dropped — a client cannot read an attribute by guessing the name. Standard OIDC claims (sub, email, name, etc.) follow the spec and are not subject to the whitelist.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Assigning Scopes to Clients

Add allowed scopes on the Clients → Scopes & Grants tab. A client can only request scopes it has been granted; unknown scopes are rejected with invalid_scope.

Branding

Customize the look and feel of your tenant's login pages. Branding settings let you match the authentication experience to your product's visual identity — from logos and colors to advanced CSS overrides.

Appearance

Appearance settings with live color preview

Contact Information

Login Page Toggles

Control which elements appear on your tenant's login page:

Example login page with custom branding applied

Custom CSS

For full control over the login page appearance, provide a CSS file URL in your branding settings. The file is loaded after the default styles, so your rules take precedence.

Dark Mode

The login app ships with light, dark, and system themes. Users pick from a toggle on the login page; the choice persists across sessions. When set to system, the SPA tracks prefers-color-scheme live.

Light values are declared at :root; dark overrides are scoped to .dark. Tenant branding set via customCssUrl always wins — so your colors persist regardless of the user's theme.

Settings

Configure tenant-wide security policies, webhooks, and environment settings. These settings apply globally across all clients unless overridden at the client level.

Password Policy

Define the password complexity requirements for all users in your tenant:

Password policy configuration

MFA Policy

The tenant-wide MFA policy sets the default multi-factor authentication behavior. Individual clients can override this setting.

Session & Lockout

Control session duration and account lockout behavior:

Session and lockout configuration

Webhooks

Webhooks let you react to authentication events in real time. Two events (onUserAuthenticated, onTokenIssued) are enforceable — by default they fire asynchronously and don't block the user, but you can opt in to enforcement per event so a non-2xx response or {"allow": false} body rejects the action. The remaining events are notifications — always fire-and-forget, never block.

Additional webhook settings:

Webhook event configuration

Verifying webhooks

Once any webhook URL is configured, Authagonal mints a per-tenant signing secret (a whsec_… value shown read-only under Settings → Webhooks). Every outbound delivery carries an X-Authagonal-Signature: t=<unix>,v1=<hex> header, where v1 is HMAC-SHA256(secret, "{t}.{body}") computed over the raw request body. Recompute it on your endpoint and constant-time-compare to confirm the request genuinely came from Authagonal and wasn't tampered with — and reject deliveries whose t is too old to block replays.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Maintenance Window

Set a preferred maintenance window for disruptive operations such as certificate rotations and infrastructure updates. Choose a UTC hour (0–23) — the portal also displays the equivalent time in your local timezone for convenience.

Sandbox Environment

The sandbox environment is a full clone of your production tenant, available at a separate URL. Use it to test configuration changes, SSO integrations, and webhook endpoints without affecting live users.

The sandbox is accessible at {slug}-sandbox.authagonal.io.

Sandbox environment controls

Billing

Manage your subscription and billing through the portal's Billing page. This page gives you an overview of your current plan and provides access to the Stripe billing portal for managing payment methods, invoices, and plan changes.

Subscription Information

The billing page displays your current subscription details at a glance. You'll see a status badge indicating your subscription state — active, trialing, past_due, canceled, or unpaid — along with your plan name, the current billing period (start and end dates), and whether your subscription is set to cancel at the end of the current period.

Manage Subscription

Click the Manage Subscription button to open the Stripe billing portal in a new window. From there you can update your payment methods, view and download invoices, change your plan, or cancel your subscription.

If no subscription exists yet, a Setup Billing call-to-action is shown instead, which guides you through selecting a plan and entering payment details.

The billing page displays your current subscription details and provides access to Stripe

Custom Domains

Serve your authentication pages from your own domain (e.g., auth.yourdomain.com) instead of the default {slug}.authagonal.io. Custom domains give your users a seamless, branded authentication experience.

Adding a Domain

Enter the hostname you want to use in the add domain form (e.g., auth.yourdomain.com). Once added, the domain will appear in your domain list with a pending_verification status.

DNS Verification

Create a CNAME record pointing your domain to {slug}.authagonal.io. Once the DNS record is in place, click Verify to check DNS propagation.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

TLS Certificates

Once your domain is verified, you need a TLS certificate so users can connect securely over HTTPS. Authagonal supports two options:

Automatic (cert-manager) — Authagonal provisions and renews TLS certificates automatically using cert-manager. This is the recommended option for most users. No additional configuration is required.

Bring Your Own (BYO) — Upload your own certificate and private key in PEM format. This option is useful if your organization requires certificates from a specific certificate authority. Certificate expiry is tracked so you can renew before it lapses.

Domain Status

Each domain displays a status badge indicating its current state: pending_verification (DNS not yet confirmed), verified (DNS confirmed, TLS pending), active (fully operational), or failed (configuration issue detected).

The domain list displays each custom domain and its current status

Upload your own TLS certificate and private key in PEM format

Email Configuration

Configure how your tenant sends transactional emails — verification, password reset, and MFA notifications. Choose between the default shared sender, a verified custom domain via Resend, or your own SMTP server.

Email Providers

Sender Identity

Sender email and name are shared across all provider modes. Sender email is required; sender name falls back to the tenant name when empty.

Resend Custom Domain

Verify your sending domain with Resend once, then use it as the From address for this tenant. DNS TXT records (SPF, DKIM) are provided by the Domains page; Resend validates them automatically.

Custom SMTP

Bring your own SMTP server — useful for internal relays, vendors not covered by Resend, or regulatory pinning.

Custom Sending Domain

When using the Resend provider, you can register your own domain so emails come from your brand (e.g. noreply@acme.com) instead of @authagonal.io.

1. Go to Settings → Email and select the Resend Custom Domain provider.
2. Enter your domain name and click Register.
3. Add the DNS records shown (DKIM, SPF, and return path) to your domain's DNS.
4. Click Check Verification — once DNS propagates (usually 1–10 minutes), the domain status will change to verified.

Testing

Use the Send Test Email button in Settings → Email to verify your configuration. A test email will be sent to your admin email address using the currently saved settings.

Audit Log

The Audit Log provides a read-only record of all administrative actions performed on your tenant. Every change made through the portal or API is captured with full context, giving you a complete trail for compliance and troubleshooting.

Log Columns

Tracked Actions

The following administrative actions are recorded in the audit log:

The audit log provides a complete record of all administrative actions

Backups

Authagonal automatically backs up your tenant data on an hourly schedule. Backups include all users, groups, roles, clients, SSO connections, SCIM tokens, branding, and settings. You can view backup history and download the latest complete backup from the Backups page.

How Backups Work

• A full backup runs once daily, capturing every table in your tenant's storage shard.
• Incremental backups run hourly, capturing only rows that changed since the last backup.
• Backups are stored in Azure Blob Storage with the same managed identity used by your tenant.
• Deleted records are tracked via tombstones and included in backups for audit completeness.

Downloading Backups

Click Download Latest to get a ZIP file containing the most recent full backup merged with all subsequent incremental backups. Each table is exported as a JSONL file (one JSON object per line).

Provisioning Apps

Provisioning apps receive real-time webhook notifications when users are created or authenticated in your tenant. This enables downstream systems to automatically set up accounts, assign licenses, or sync user data without manual intervention.

How It Works

When a user event occurs (creation or authentication), Authagonal calls your provisioning app's callback URL using the TCC (Try/Confirm/Cancel) pattern. This three-phase approach ensures reliable provisioning across multiple downstream systems:

Webhook Payload

Each webhook request includes a JSON payload with the following fields:

Adding a Provisioning App

To add a provisioning app, provide a name, a callback URL, and an optional API key. The API key is sent as a Bearer token in the Authorization header of each webhook request, allowing your app to authenticate requests from Authagonal.

Testing

Click Test next to any provisioning app to send a test request to your callback URL. The test results display the HTTP status code and response body, helping you verify that your app is receiving and processing webhooks correctly.

Test provisioning apps to verify webhook delivery and response handling

Plan Limits

The maximum number of provisioning apps is configurable per tenant, with a default limit of 6. This limit can be adjusted by an admin if your workflow requires additional provisioning targets.

Team

The Team page manages portal administrators — the people who can access and configure your tenant through the management portal. All team members have full administrative access to every aspect of your tenant configuration.

Admin List

The admin list displays each team member's name, email address, and the date they were added. A "You" indicator is shown next to the current user's row so you can easily identify your own account.

Inviting Admins

To invite a new team member, provide their email address, name, and a temporary password (minimum 8 characters). The invited user signs in with the temporary password and should change it on first login.

Invite Fields

Admin invitations create a fully provisioned user — no email round-trip required.

Removing Admins

Click Remove next to any team member to revoke their access. A confirmation dialog is shown before the removal is finalized. You cannot remove yourself — there must always be at least one admin on the team.

Manage portal administrators from the Team page

Import & migrate

Migrate an existing identity system into your Authagonal tenant. Two sources are supported — Duende IdentityServer (a SQL Server database) and Auth0 (the Management API). Each runs a read-only preview so you can review exactly what will be copied before committing.

Import from Duende IdentityServer

Migrate clients, scopes, users, and roles from an existing Duende IdentityServer SQL Server database into your Authagonal tenant. The import runs in two phases — preview and commit — so you can review what will be copied before any changes are made.

What Gets Imported

The importer reads from Duende's ConfigurationDb and ASP.NET Identity tables and writes mapped rows into your tenant. Short-lived artifacts like persisted grants, device codes, and signing keys are skipped.

Preview Before Commit

Paste your Duende ConfigurationDb / IdentityDb connection string and click Run preview. The preview opens a read-only connection and counts every row that would be imported — no writes occur.

• Entity counts for clients, scopes, users, roles, and role assignments.
• Owner collisions — tenant admins whose existing <code>userId</code> differs from the incoming Duende <code>sub</code>.
• Warnings for unknown tables and unmapped columns so you know what will be dropped.

Preview panel with counts, collisions, and warnings

Password Hashes

Duende stores passwords using ASP.NET Identity V3 (PBKDF2). Authagonal's PasswordHasher verifies that format directly and rehashes to the native format on the first successful sign-in — users keep their existing passwords without a reset flow.

Owner UserId Rotation

If a tenant admin's email matches a user in the Duende database, the admin's Authagonal userId is rotated to match the Duende sub. This keeps tokens and audit entries consistent after cutover. The preview lists every collision before you commit.

Running the Import

Click Start import after reviewing the preview. The commit phase writes clients, scopes, users, roles, and external-login references into your tenant stores. Duplicate clientId, scope name, email, and role name rows are skipped — the importer is safe to re-run.

What's Not Imported

• Persisted grants, device codes, server-side sessions — short-lived, regenerated automatically.
• Signing keys — Authagonal issues its own per-tenant keys.
• Custom columns and tables — anything outside Duende's standard schema is surfaced as a warning so you know the data was dropped.
• Disabled clients — imported in a disabled state; re-enable them from the Clients page when ready.

Import from Auth0

Connect Authagonal to your Auth0 tenant’s Management API and bring your applications, APIs, roles, users, and enterprise connections across. Imported user and application IDs are preserved, so existing sub and client_id references keep resolving after cutover.

What you’ll need

Create a Machine-to-Machine application in Auth0 authorized for the Management API, granted these read scopes: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Paste its domain, client ID, and client secret into the import form — they’re used only for the import.

What Gets Imported

Passwords

Auth0’s Management API never returns password hashes. If you have Auth0’s support-assisted bulk password export (NDJSON), provide it — bcrypt hashes import verbatim and your users keep their passwords with no reset. That file also carries your full user set, lifting Auth0’s 1,000-user API listing limit. Without it, users import as profiles and set a new password on first sign-in.

API Reference

Each tenant exposes a standards-compliant OIDC server at https://{slug}.authagonal.io. All endpoints follow the OAuth 2.0 and OpenID Connect specifications. This reference covers every endpoint your application may need to interact with.

Authorization Code Flow with PKCE

OIDC Discovery & JWKS

The discovery document lets OIDC client libraries automatically configure themselves. No authentication is required for either endpoint.

GET /.well-known/openid-configuration

Returns the OpenID Provider Configuration document. The response includes all metadata your client needs to interact with this tenant.

GET /.well-known/openid-configuration/jwks

Returns the JSON Web Key Set used for verifying token signatures. The response contains a keys array with RSA public keys, each including kty, use, kid, alg, n, and e fields.

curl https://acme.authagonal.io/.well-known/openid-configuration

Authorization Endpoint

GET /connect/authorize

Initiates an authorization code flow. The user must have an active session or they will be redirected to the login page. On success, the user is redirected back to your application with an authorization code.

Success response: 302 redirect to redirect_uri with code and state query parameters.

Error response: 302 redirect with error, error_description, and state query parameters.

Pushed Authorization Requests (PAR)

RFC 9126. Instead of putting every authorize parameter on the URL, your client POSTs them to /connect/par with normal client authentication and gets back a short-lived opaque request_uri. The browser then visits /connect/authorize?client_id=...&request_uri=... — nothing else lands in browser history, server logs, or Referer headers, and the server has already integrity-checked the parameters under client auth.

POST /connect/par

Client authentication is the same as /connect/token: HTTP Basic with client_id/client_secret, or form-encoded credentials. Public clients post without a secret. The body carries the same parameters you would normally send to /connect/authorize; request_uri itself is rejected (chaining a PAR is forbidden by §2.1 of the spec). Returns 201 Created.

Response

On the follow-up GET /connect/authorize?client_id=…&request_uri=…, all other parameters are pulled from the pushed payload and any extra query parameters are ignored. The client_id on the authorize call must match the client that pushed the request. Once consumed (or once expires_in elapses), the request_uri is removed from the store.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Token Endpoint

POST /connect/token

Exchanges credentials for tokens. Requests must use Content-Type: application/x-www-form-urlencoded. Client authentication can be provided via HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) or as form body parameters (client_id + client_secret).

Authorization Code Grant

Refresh Token Grant

Client Credentials Grant

Device Code Grant

Token response:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

UserInfo Endpoint

GET /connect/userinfo

Returns claims about the authenticated user. Requires a valid access token with the openid scope.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token Introspection (RFC 7662)

POST /connect/introspect

Validates a token and returns its metadata. Requires client credentials (Basic auth or form body parameters).

Active token response:

Inactive token response: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Token Revocation (RFC 7009)

POST /connect/revocation

Revokes a previously issued token. Requires client credentials.

The endpoint always returns 200 OK, even for invalid or already-revoked tokens, per the RFC 7009 specification.

Device Authorization (RFC 8628)

POST /connect/deviceauthorization

Initiates the device authorization flow for input-constrained devices (CLIs, smart TVs, IoT devices). The device displays a code to the user, who then approves the request on a separate device with a browser.

Response:

Approval flow: The user visits the verification_uri, enters the user_code, and approves the request. Meanwhile, the device polls the token endpoint with the device_code.

Polling error codes:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

End Session / Logout

GET POST /connect/endsession

Signs out the current user session, triggers back-channel logout to all clients with a registered BackChannelLogoutUri, and revokes all grants.

If a valid post_logout_redirect_uri is provided and matches a registered URI, the user receives a 302 redirect. Otherwise, a JSON response confirms the session has been ended.

SCIM 2.0 API Reference

Authagonal supports the SCIM 2.0 protocol for automated user and group provisioning. Identity providers such as Okta, Azure AD, and OneLogin can use this API to keep your Authagonal tenant in sync with your corporate directory.

Base URL: https://{slug}.authagonal.io/scim/v2

Authentication: All requests require a Bearer token. Generate a SCIM token in the portal under Settings > SCIM Provisioning.

Common headers:

List endpoints support pagination via startIndex (1-based) and count (max 200) query parameters, and filtering via the filter parameter (e.g. userName eq "user@example.com").

Users

GET /scim/v2/Users — List users with optional pagination and filtering.

GET /scim/v2/Users/{id} — Get a single user by their Authagonal user ID.

POST /scim/v2/Users — Create a new user. Returns 201 Created.

PUT /scim/v2/Users/{id} — Full replacement of a user resource. All fields must be provided.

PATCH /scim/v2/Users/{id} — Partial update using SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Soft deletes the user (deactivates the account and revokes all tokens). Returns 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Groups

GET /scim/v2/Groups — List all groups with optional pagination and filtering.

GET /scim/v2/Groups/{id} — Get a single group by ID, including its members list.

POST /scim/v2/Groups — Create a new group. Returns 201 Created.

PUT /scim/v2/Groups/{id} — Full replacement of a group resource (including its member list).

PATCH /scim/v2/Groups/{id} — Partial update for adding or removing group members.

DELETE /scim/v2/Groups/{id} — Hard deletes the group. Returns 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

Portal API (automation)

The Portal API lets your own backend automate everything you can do in the portal — manage users, clients, groups, roles, scopes, SSO connections, and settings — using a machine-to-machine credential. It is the same API the portal UI calls.

Base URL: https://portal-api.<your-domain>/api/v1. Requests authenticate with a Bearer access token; the tenant is taken from the token, not the URL.

Creating an API credential

In the portal, open Clients → Create API credential, pick an access level, and give it a name. Authagonal generates an OAuth client_credentials client wired for the Portal API and returns a client ID and secret.

Access levels

Getting a token

Exchange the credential for an access token at your tenant's token endpoint — https://<your-tenant>.<your-domain>/connect/token — then send the token as a Bearer header to the Portal API. Tokens are valid for one hour.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoints

All paths are relative to the base URL and require a Bearer access token. The scope beside each group is the minimum credential access level it needs. List endpoints accept startIndex and count query parameters.

GET/api/v1/clients— List OAuth clients.

GET/api/v1/clients/{id}— Get a single client by ID.

POST/api/v1/clients— Create a client. Returns the client ID and, for confidential clients, a one-time secret.

PUT/api/v1/clients/{id}— Update a client (redirect URIs, grant types, token lifetimes, PKCE/PAR requirements).

DELETE/api/v1/clients/{id}— Delete a client.

POST/api/v1/clients/api-credential— Mint a machine-to-machine Portal API credential.

GET/api/v1/users— List users. Supports startIndex, count, and search (email / name prefix).

GET/api/v1/users/count— Total user count for the tenant.

GET/api/v1/users/stats/mfa— MFA enrollment statistics.

GET/api/v1/users/{id}— Get a single user.

POST/api/v1/users— Create a user with an email and password.

PUT/api/v1/users/{id}— Update a user (profile, email, enabled/blocked state).

DELETE/api/v1/users/{id}— Delete a user.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— List roles.

POST/api/v1/roles— Create a role.

DELETE/api/v1/roles/{id}— Delete a role.

POST/api/v1/roles/assign— Assign a role to a user.

POST/api/v1/roles/unassign— Remove a role from a user.

GET/api/v1/groups— List groups.

GET/api/v1/groups/{id}— Get a group with its members.

POST/api/v1/groups— Create a group.

POST/api/v1/groups/{id}/members— Add members to a group.

DELETE/api/v1/groups/{groupId}/members/{userId}— Remove a member from a group.

DELETE/api/v1/groups/{id}— Delete a group.

GET/api/v1/group-role-mappings— List group-to-role mappings (roles granted at token issuance by group membership).

GET/api/v1/scopes— List API scopes.

POST/api/v1/scopes— Create a scope.

DELETE/api/v1/scopes/{name}— Delete a scope.

GET/api/v1/saml/connections— List SAML connections.

POST/api/v1/saml/connections— Create a SAML connection.

DELETE/api/v1/saml/connections/{id}— Delete a SAML connection.

GET/api/v1/oidc/connections— List OIDC connections.

POST/api/v1/oidc/connections— Create an OIDC connection.

DELETE/api/v1/oidc/connections/{id}— Delete an OIDC connection.

GET/api/v1/sso/domains— List the domains routed to SSO connections (home-realm discovery).

GET/api/v1/branding— Get the tenant branding (colors, logo, supported languages).

PUT/api/v1/branding— Update the tenant branding.

GET/api/v1/settings— Get tenant settings (webhooks, public sign-up, token policy).

PUT/api/v1/settings— Update tenant settings.

POST/api/v1/settings/webhook-secret/regenerate— Rotate the webhook signing secret.

POST/api/v1/settings/test-email— Send a test email with the current email configuration.

GET/api/v1/custom-domains— List custom login domains and their verification status.

POST/api/v1/custom-domains— Add a custom domain.

POST/api/v1/custom-domains/{domain}/verify— Trigger DNS verification for a custom domain.

DELETE/api/v1/custom-domains/{domain}— Remove a custom domain.

GET/api/v1/email/domains— List sender email domains.

GET/api/v1/audit— Query the tenant audit log.

Example: create a user

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.com",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "ada@acme.com" }

Authentication Flows

Authentication flows cover how end users interact with your Authagonal tenant — logging in, registering, resetting passwords, and setting up MFA. These endpoints are used by the hosted login page and can be called directly if you are building a custom login UI.

Login

POST /api/auth/login

Authenticates a user with email and password. On success, signs a session cookie and returns the user profile. If MFA is configured, the response indicates that a second factor is required before the session is fully established.

Request body:

{
  "email": "user@example.com",
  "password": "correct-horse-battery-staple"
}

Success response:

MFA required response: When the user has MFA enrolled, the response includes mfaRequired: true along with a challengeId and a methods array listing available MFA methods.

MFA setup required response: When the tenant requires MFA but the user has not yet enrolled, the response includes mfaSetupRequired: true with a setupToken for the enrollment flow.

Error responses:

SSO check: If the user's email domain has an SSO connection configured, the login endpoint returns sso_required with a redirectUrl. The client should redirect the user to the SSO provider.

Account lockout: After maxFailedAttempts consecutive failed login attempts, the account is locked for lockoutDurationMinutes. Both values are configurable in tenant settings.

Registration

POST /api/auth/register

Creates a new user account. A verification email is sent automatically — the user must verify their email before they can log in.

Request body:

{
  "email": "newuser@example.com",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Success: 201 Created with the userId of the new account.

Error responses:

Password Reset

POST /api/auth/forgot-password

Requests a password reset email. The endpoint always returns a success response regardless of whether the email exists, to prevent email enumeration.

{
  "email": "user@example.com"
}

POST /api/auth/reset-password

Resets the user's password using the token from the email link.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Side effects of a successful password reset:

• Failed login attempt counter is reset to zero
• All existing refresh tokens are revoked
• A new security stamp is generated (invalidating all existing sessions)

MFA Setup & Verification

Authagonal supports three MFA methods: TOTP (authenticator apps), WebAuthn (security keys and biometrics), and single-use recovery codes.

TOTP Setup

POST /api/auth/mfa/totp/setup — Returns a QR code data URI and a manual entry key. The user scans the QR code with their authenticator app (Google Authenticator, Authy, 1Password, etc.), then confirms enrollment.

POST /api/auth/mfa/totp/confirm — Confirms TOTP enrollment by validating a 6-digit code from the authenticator app.

{
  "code": "123456"
}

WebAuthn Setup

POST /api/auth/mfa/webauthn/setup — Returns credential creation options for the WebAuthn API. The browser calls navigator.credentials.create() with these options.

POST /api/auth/mfa/webauthn/confirm — Confirms WebAuthn enrollment by submitting the attestation response from the browser.

Recovery Codes

POST /api/auth/mfa/recovery/generate — Generates 10 single-use 8-character recovery codes. Each code can be used exactly once to bypass MFA.

MFA Verification

POST /api/auth/mfa/verify — Completes the MFA challenge after a successful password login.

MFA Status

GET /api/auth/mfa/status — Returns the user's currently enrolled MFA methods.

SSO Login Flow

Authagonal supports both SAML 2.0 and OIDC-based SSO connections. Domain-based routing automatically detects which SSO provider to use based on the user's email address.

SSO Check

GET /api/auth/sso-check?email=user@acme.com

SAML Flow

The user is redirected to GET /saml/{connectionId}/login which sends a SAML AuthnRequest to the identity provider. The IdP authenticates the user and posts a SAML response back to the Assertion Consumer Service (ACS) endpoint. Authagonal validates the assertion, creates or updates the user, and signs a session cookie.

SAML metadata for configuring your IdP is available at GET /saml/{connectionId}/metadata.

OIDC Flow

The user is redirected to GET /oidc/{connectionId}/login which redirects to the upstream identity provider with PKCE. After the user authenticates, the callback at /oidc/callback exchanges the authorization code, validates the ID token, and creates or updates the user.

JIT Provisioning: Both SAML and OIDC flows support just-in-time provisioning. If the user does not already exist in the tenant, they are created automatically from the identity provider's claims. If they do exist, their profile attributes are updated to match the latest values from the provider.

Build a custom login UI

Replace Authagonal's hosted login, registration, password-reset and MFA screens with your own UI, while Authagonal keeps handling authentication, MFA, SSO, sessions and token issuance. Two routes: use our React component library, or call the auth API directly from any framework. It's opt-in — enable Custom login UI in tenant settings first.

Prerequisite: a custom domain on your root

The login session is a first-party cookie, so your UI and the Authagonal auth server must share a registrable domain. Point a custom auth domain at Authagonal on the same root your app runs on — e.g. auth at login.acme.com, app at app.acme.com. The Custom login UI setting stays disabled until an active custom domain exists.

Also add your UI's origin (e.g. https://app.acme.com) to your OAuth client's Allowed CORS origins — the same list you set for the token exchange.

React: @authagonal/login

npm i @authagonal/login ships the auth logic and UI as one package — the same one Authagonal's hosted login is built on. Pick your altitude:

• Full app — drop in App and theme it via branding.
• Compose pages — use LoginPage, MfaChallengePage, ResetPasswordPage… inside your own layout.
• Primitives + logic — build your own screens with AuthLayout/Button/Input and the API client (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Any framework: call the auth API

Not on React? Call the auth-flow endpoints directly (under /api/auth), then hand off to the standard OIDC /connect/authorize flow. Send credentials: 'include' so the session cookie is stored.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"jane@acme.com","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Plans & Limits

Authagonal offers four plan tiers. All plans include all features — the only difference is the Monthly Active User (MAU) limit and overage pricing.

Plan Tiers

Monthly Active Users (MAU)

A Monthly Active User is any unique user who successfully authenticates at least once during a billing month. Users provisioned via SCIM but who haven't logged in don't count toward your MAU total.

Overage — If your plan supports overage, users beyond the MAU limit are billed at the per-user rate shown in the plan table above. You can set an overage cap to limit your maximum spend for the billing period.

Enforcement — If your plan doesn't support overage (Starter), users beyond the MAU limit cannot log in until the next billing period or until you upgrade to a plan that supports overage.