Session Management

Auris manages user sessions through a combination of OAuth2 tokens (access tokens and refresh tokens) and server-side session records. This guide explains the session lifecycle, how to configure session policies, how token rotation works, and how to revoke sessions programmatically.

Session Lifecycle

When a user authenticates through the hosted login flow, Auris creates the following:

1. OAuth Session — A server-side record tracking the authentication state, stored with an httpOnly cookie on the hosted login domain. This session has a 30-minute TTL and is used only during the login flow itself.

2. Access Token — A short-lived JWT (default: 60 minutes) returned to your application. Used as a Bearer token to authenticate API requests.

3. Refresh Token — A long-lived opaque token (default: 30 days) used to obtain new access tokens without requiring the user to log in again.

4. Login Session — A server-side record in Auris that tracks the active session, including device information, IP address, and the authentication methods used (acr/amr claims).

The access token is the primary credential your application uses. When it expires, the SDK automatically uses the refresh token to obtain a new access token (if autoRefresh is enabled). The refresh token itself can be rotated on each use for additional security.

Configuring Session Policies

Session policies control how long sessions remain valid and under what conditions they expire. Configure these in the Auris Console under Settings then Security.

Session Lifetime Settings

Configuring via Console

1. Navigate to Console then Settings then Security
2. Under the Session Policy section, adjust the values
3. Click Save

Changes take effect immediately for new sessions. Existing sessions continue with their original policy until they expire.

Configuring via API

curl -X PATCH https://auth.yourdomain.com/api/settings/security \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "accessTokenLifetime": 3600,
    "refreshTokenLifetime": 2592000,
    "absoluteSessionExpiry": 2592000,
    "idleTimeout": 604800,
    "refreshTokenRotation": true
  }'

All durations are in seconds.

Token Rotation

How Refresh Token Rotation Works

When refresh token rotation is enabled (recommended), the token exchange flow works like this:

1. Your application sends the current refresh token to the token endpoint
2. Auris validates the refresh token and checks that it has not been revoked
3. Auris issues a new access token and a new refresh token
4. The old refresh token is immediately invalidated
5. Your application stores the new refresh token, replacing the old one

Client                              Auris Token Endpoint
  |                                        |
  |  POST /api/auth/token                  |
  |  grant_type=refresh_token              |
  |  refresh_token=old_RT_abc123           |
  |--------------------------------------->|
  |                                        |  Validate old_RT_abc123
  |                                        |  Invalidate old_RT_abc123
  |                                        |  Issue new_AT + new_RT_def456
  |  { access_token, refresh_token }       |
  |<---------------------------------------|
  |                                        |
  |  (old_RT_abc123 is now invalid)        |

Why Rotation Matters

Without rotation, a stolen refresh token can be used indefinitely (until it expires) to generate new access tokens. With rotation:

• Each refresh token can only be used once
• If an attacker steals and uses a refresh token, the legitimate user’s next refresh attempt fails (because the token was already consumed)
• Auris detects this as a reuse anomaly and can invalidate all tokens in the family, forcing re-authentication

Reuse Detection

If Auris receives a refresh token that has already been consumed (indicating it was stolen and replayed), it:

1. Invalidates all refresh tokens in the same token family
2. Records a security event in the audit log
3. The user must re-authenticate on all devices

This is the primary defense against refresh token theft in browser-based applications.

Revoking Sessions Programmatically

Revoke a Specific Session

To revoke a single session (e.g., when a user clicks “Sign out” on a specific device):

curl -X DELETE https://auth.yourdomain.com/api/sessions/{sessionId} \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

Or from the SDK:

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.yourcompany.com',
  clientId: 'your-client-id',
})
 
// Log out the current session
await auris.logout({ returnTo: 'https://yourapp.com' })

Revoke All Sessions for a User

In a security incident (compromised account, stolen credentials), you may need to immediately terminate all of a user’s sessions across all devices:

curl -X POST https://auth.yourdomain.com/api/users/{userId}/revoke-sessions \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

This call:

1. Invalidates all refresh tokens for the user
2. Marks all active sessions as revoked
3. The user’s access tokens will continue to work until they expire (they are stateless JWTs), but they cannot be refreshed

To also invalidate access tokens immediately, your resource server must check the session status on each request rather than relying solely on JWT expiry. The @auris/nextjs middleware does this automatically via the verifySessionActive() call.

Force Re-authentication

To require a user to re-authenticate on their next interaction without terminating existing sessions:

curl -X POST https://auth.yourdomain.com/api/users/{userId}/force-reauth \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

This invalidates all refresh tokens but allows current access tokens to complete in-flight requests. The next time the SDK attempts a token refresh, it will fail and redirect the user to login.

Multi-Device Session Management

Auris tracks sessions per device, allowing users and administrators to view and manage active sessions across all devices.

Listing Active Sessions

Users can view their own sessions:

curl https://auth.yourdomain.com/api/user/sessions \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

Response:

{
  "ok": true,
  "data": [
    {
      "id": "sess_abc123",
      "deviceInfo": "Chrome 120 on macOS",
      "ipAddress": "203.0.113.42",
      "location": "Milan, Italy",
      "lastActiveAt": "2026-01-15T14:30:00Z",
      "createdAt": "2026-01-10T09:00:00Z",
      "isCurrent": true
    },
    {
      "id": "sess_def456",
      "deviceInfo": "Safari on iPhone 15",
      "ipAddress": "198.51.100.17",
      "location": "Rome, Italy",
      "lastActiveAt": "2026-01-14T18:00:00Z",
      "createdAt": "2026-01-12T11:00:00Z",
      "isCurrent": false
    }
  ]
}

Revoking a Specific Device Session

A user can revoke any session that is not their current one:

curl -X DELETE https://auth.yourdomain.com/api/user/sessions/sess_def456 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

Admin Session Management

Administrators can view and revoke sessions for any user in the Console:

1. Navigate to Users and select the user
2. Open the Sessions tab
3. View all active sessions with device, IP, location, and last activity
4. Click Revoke on individual sessions or Revoke All to terminate all sessions

Admins can also access this via the API:

# List all sessions for a user (admin)
curl https://auth.yourdomain.com/api/admin/sessions?userId={userId} \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"
 
# Revoke a specific session (admin)
curl -X DELETE https://auth.yourdomain.com/api/admin/sessions/{sessionId} \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

Session Security Best Practices

Use short access token lifetimes. Access tokens are stateless and cannot be individually revoked. Keep them short (15-60 minutes) so that revocation takes effect quickly when refresh tokens are invalidated.

Enable refresh token rotation. This is the single most effective defense against token theft. Auris enables it by default — do not disable it unless you have a specific technical reason.

Set a reasonable absolute session expiry. Even with refresh token rotation, sessions should have an upper bound. For most applications, 30 days is a good default. For high-security applications (banking, healthcare), consider 1-7 days.

Configure idle timeout. Users who stop using the application should be logged out automatically. A 7-day idle timeout balances security and convenience for most use cases.

Verify sessions server-side for sensitive operations. For actions like changing email, enabling/disabling MFA, or initiating financial transactions, call the Auris session verification endpoint to confirm the session is still active and has not been revoked:

import { getSession } from '@auris/nextjs/server'
 
export async function transferFunds(req: Request) {
  const session = await getSession()
  if (!session) {
    return Response.json({ error: 'Session expired' }, { status: 401 })
  }
 
  // Session is valid and active — proceed
}

Monitor session events. Subscribe to the login.succeeded and user.session_revoked webhook events to track session creation and termination in your audit system.

Related Guides

• Hosted Login (PKCE) — How tokens are issued during the login flow
• Multi-Factor Authentication — Adding a second factor to session creation
• Attack Protection — Brute-force lockout and suspicious login detection
• Rate Limiting — API rate limits on authentication endpoints