Quick Start

Configure Anonymous Sessions and create your first guest user session in five steps.

Prerequisites

1. An Auth0 account and tenant
2. An application registered in Auth0
3. An API (resource server) configured in Auth0

Step 1: Configure Anonymous Sessions for your tenant

Set the anonymous session lifetime and token format at the tenant level.

Dashboard

1. Navigate to Dashboard > Settings > Tenant Settings > Advanced.
2. Scroll to Session Expiration.
3. Enter a value for Anonymous Session Lifetime (in seconds). Auth0 recommends 30 days or longer for most applications.
4. Select whether to use JWE (encrypted) or JWT (plain) for session tokens. Use JWE in production to prevent clients from reading token contents.
5. Select Save.

Management API

Make a PATCH request to the /api/v2/tenants/settings endpoint:

curl --request PATCH \
  --url 'https://YOUR_DOMAIN/api/v2/tenants/settings' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "anonymous_session_lifetime": 2592000,
    "anonymous_session_token_format": "jwt"
  }'

Step 2: Enable Anonymous Sessions for your application

Dashboard

1. Navigate to Dashboard > Applications > Applications and select your application or create a new one.
2. Select the Settings tab.
3. Scroll down to Anonymous Sessions.
4. Toggle Enable Anonymous Sessions to on.
5. Select Save Changes.

Management API

Make a PATCH request to the /api/v2/clients/{id} endpoint:

curl --request PATCH \
  --url 'https://YOUR_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "can_create_anonymous_sessions": true }'

Step 3: Enable Anonymous Access for your API

Dashboard

1. Navigate to Dashboard > Applications > APIs and select your API.
2. Select the Settings tab.
3. Scroll to Anonymous Access.
4. Toggle Allow Anonymous Access to on.
5. Select which scopes are available to anonymous users.
6. Select Save.

Management API

Make a PATCH request to the /api/v2/resource-servers/{id} endpoint:

curl --request PATCH \
  --url 'https://YOUR_DOMAIN/api/v2/resource-servers/YOUR_API_ID' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "allow_anonymous_access": true,
    "token_lifetime_for_anonymous_access": 604800
  }'

Step 4: Create your first anonymous session

Make a POST request to the /anonymous/token endpoint:

curl --request POST \
  --url 'https://YOUR_DOMAIN/anonymous/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "audience": "YOUR_AUDIENCE",
    "scope": "anon"
  }'

Response:

{
  "session_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0...",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Verify the contents of both the session token and access token at jwt.io.

Step 5: Update the session with metadata

Include the session_token from the previous step to continue the same session and add metadata:

curl --request POST \
  --url 'https://YOUR_DOMAIN/anonymous/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "audience": "YOUR_AUDIENCE",
    "scope": "anon",
    "session_token": "PREVIOUS_SESSION_TOKEN",
    "metadata": {
      "language": "en",
      "country": "US"
    }
  }'

The response returns a new session token and access token. The session token now contains the metadata you provided. Verify the updated contents at jwt.io.

Next steps

• Transfer Anonymous Sessions to Users — Migrate guest activity to authenticated accounts on sign-up or login.
• Claims Mapping — Include session metadata in access tokens without writing Actions code.
• Anonymous Sessions Best Practices — Security and performance recommendations.