Introduction

Authentication overview

Authalla combines passwordless and SSO login methods with OAuth2/OIDC tokens, so your apps can authenticate users and call APIs with standard flows.

Login methods

These are the end-user authentication methods supported by Authalla-hosted screens:

  • Passkeys (WebAuthn)
  • Magic links and OTPs
  • SSO connections (social and enterprise)

OAuth2/OIDC flows we support

Authalla’s OAuth2/OIDC implementation is intentionally focused on modern, secure flows:

  • Authorization Code Flow (OIDC) with PKCE: the only supported response_type is code.
  • Refresh Token grant: for rotating access tokens, issued only when offline_access is requested.
  • Client Credentials grant: machine-to-machine flow for confidential clients.
  • Not supported: implicit flow and device code flow.

For a working PKCE example, see the OAuth2 & OIDC guide.

Authorize flow (high level)

At a high level, the authorization code flow looks like this:

  1. Your app redirects the user to https://{tenant-id}.authalla.com/oauth2/authorize.
  2. Authalla authenticates the user (passkey, magic link, or SSO) and validates the request.
  3. Authalla redirects back to your app with a one-time code and the original state.
  4. Your backend exchanges the code at https://{tenant-id}.authalla.com/oauth2/token.
  5. Authalla returns tokens (access token, optional refresh token, optional ID token).
sequenceDiagram
    participant App as App
    participant AuthallaAuthorize as AuthallaAuthorize
    participant AuthallaToken as AuthallaToken
    App->>AuthallaAuthorize: Redirect /oauth2/authorize (code, state, PKCE)
    AuthallaAuthorize-->>App: Redirect back with code + state
    App->>AuthallaToken: POST /oauth2/token (code + code_verifier)
    AuthallaToken-->>App: access_token + optional refresh_token + optional id_token

Tokens you receive

  • Access token: JWT bearer token used to call APIs. Short-lived (default 15 minutes).
  • Refresh token: opaque token used to get new access tokens (default 30 days). Issued only when offline_access is requested, rotated on use, and has a sliding TTL (each refresh issues a new token that expires at now + TTL).
  • ID token: OIDC JWT with user identity claims (default 15 minutes). Issued when openid scope is present for user-auth flows.

If you only need API access without a user, use Client Credentials to obtain access tokens without ID tokens or refresh tokens.

Security measures

Authalla enforces the following protections by default:

  • Redirect URI allowlist: redirect_uri must match a configured callback URL.
  • PKCE: required for public clients and verified during code exchange.
  • State required: state is mandatory on authorization requests.
  • Auth code replay detection: codes are one-time use; reuse revokes related tokens.
  • Refresh token rotation: refresh tokens are revoked and replaced on use.
  • Hashed token storage: access and refresh tokens are stored as SHA-256 hashes.
  • JWT signing and JWKS: access/ID tokens are signed with RS256 and published via JWKS.
  • No-store token responses: token responses are sent with Cache-Control: no-store.

For more on session policies and rotation, see Sessions & tokens.

Previous
Installation
Next
Passkeys