Sessions & tokens

Sessions keep users signed in. Tokens are the credentials your apps use to call APIs.

For a full flow overview, see Authentication overview.

Sessions

• Sessions keep a user signed in across pages and refreshes.
• Sessions are used during /oauth2/authorize to complete login.

Token types

Authalla issues three kinds of tokens:

• Access token (JWT): used by your API to authorize requests.
• ID token (JWT): OpenID Connect identity token for the client app.
• Refresh token: used to mint new access/ID tokens. Refresh tokens are rotated on every use, and the refresh token TTL is sliding (see below).

Refresh tokens are only issued when the offline_access scope is granted.

Token lifetimes

Defaults (per tenant):

• Access token: 15 minutes
• ID token: 15 minutes
• Refresh token: 30 days

You can override these in the Admin UI:

1. Open the tenant.
2. Go to General → Token Lifetimes.
3. Enter a value in seconds (for example 900 for 15 minutes, or 2592000 for 30 days).

Changes apply to newly issued tokens.

Refresh token TTL is sliding (rotating refresh tokens)

Authalla uses refresh token rotation. When a refresh token is used successfully:

• The old refresh token is revoked.
• A new refresh token is issued.
• The new refresh token expires at now + refresh token TTL.

This means the refresh token TTL acts like an inactivity window. If your app refreshes regularly, the refresh session can extend beyond the original login time.

Access token claims (important ones)

• iss: issuer URL
• sub: user ID (or client ID for client_credentials)
• aud: OAuth2 client ID (the app this token is for)
• exp, iat, nbf: standard expiry and timing claims
• jti: token ID
• tid: tenant ID
• client_id: OAuth2 client ID
• scopes: granted scopes
• external_id: present when external_id scope is granted
• https://authalla.com/claims/post_login: custom claims from post-login hooks

ID token claims (important ones)

• iss, sub, aud, exp, iat, jti: standard OIDC claims
• nonce: replay protection for the client
• auth_time: time of authentication
• email, email_verified, name, picture: profile claims (scoped)
• at_hash, c_hash: hashes of access token / authorization code
• external_id: present when external_id scope is granted
• https://authalla.com/claims/post_login: custom claims from post-login hooks

JWT validation guidelines

If you're integrating Authalla into your app, always use a JWT validation library when one is available. For a full example, see Authorize middleware: validate access tokens.

At a high level, validate tokens as follows:

1. Use /.well-known/openid-configuration to discover the issuer and jwks_uri.
2. Use jwks_uri to verify the JWT signature.
3. Validate standard claims like iss, aud, and exp.
4. Enforce your app rules using scopes and tid.

If you need user profile data, call /oauth2/userinfo with the access token.

Endpoints to inspect

Authorization endpoint (/oauth2/authorize)

Required parameters:

• client_id
• redirect_uri
• response_type=code
• scope (must include openid)
• state

Optional parameters:

• nonce (ID token replay protection)
• code_challenge, code_challenge_method (PKCE; S256 recommended)
• login_hint (email hint for SSO routing)

Discovery endpoint (/.well-known/openid-configuration)

Use this to find:

• issuer
• authorization_endpoint
• token_endpoint
• jwks_uri
• supported scopes, grant types, and response types

JWKS endpoint (/.well-known/jwks.json)

Contains the public key(s) for validating Authalla JWTs for the tenant.