Create Session

Create a new session for a user

Endpoint

POST /recipe/session

Creates a new session for a user after successful authentication. Returns access and refresh tokens along with session metadata.

Request Body

userId · string · required

The user ID for whom to create the session. This can be either the primary user ID or recipe user ID depending on your authentication setup.

userDataInJWT · object · required

Custom data to be included in the access token JWT payload. This data is accessible without database queries but increases token size.

Example:

{
  "role": "admin",
  "permissions": ["read", "write"]
}

userDataInDatabase · object · required

Custom data to be stored in the database and associated with the session. This data is not included in tokens.

Example:

{
  "lastLoginIp": "192.168.1.1",
  "deviceInfo": "Chrome on MacOS"
}

enableAntiCsrf · boolean · required

Whether to enable anti-CSRF token protection for this session. Set to true for browser-based applications.

useDynamicSigningKey · boolean

Whether to use dynamic signing keys for the access token. Defaults to true for CDI version >= 2.21.

• true - Uses rotating keys for enhanced security
• false - Uses static key for simplified verification

Response

status · string

Always returns "OK" on success.

session · object

Session metadata

Show Session object

handle · string

Unique session identifier. Format: <uuid> or <uuid>_<tenantId> for non-default tenants.

userId · string

Primary user ID associated with the session.

recipeUserId · string

Recipe-specific user ID (CDI version >= 4.0).

userDataInJWT · object

The custom data included in the JWT payload.

tenantId · string

Tenant ID for the session (CDI version >= 3.0).

accessToken · object

Access token information

Show Token details

token · string

JWT access token to be sent with API requests.

expiry · number

Unix timestamp (milliseconds) when the token expires.

createdTime · number

Unix timestamp (milliseconds) when the token was created.

refreshToken · object

Refresh token information

Show Token details

token · string

Opaque refresh token used to obtain new access tokens.

expiry · number

Unix timestamp (milliseconds) when the token expires.

createdTime · number

Unix timestamp (milliseconds) when the token was created.

idRefreshToken · object

ID refresh token (deprecated in CDI >= 2.21)

Show Token details

token · string

Legacy refresh token identifier.

expiry · number

Unix timestamp (milliseconds) when the token expires.

createdTime · number

Unix timestamp (milliseconds) when the token was created.

antiCsrfToken · string

Anti-CSRF token to be included in subsequent requests (only if enableAntiCsrf is true).

Example Request

curl -X POST https://your-domain.com/recipe/session \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "userDataInJWT": {
      "role": "admin",
      "email": "[e-mail]"
    },
    "userDataInDatabase": {
      "lastLoginIp": "192.168.1.1",
      "userAgent": "Mozilla/5.0..."
    },
    "enableAntiCsrf": true,
    "useDynamicSigningKey": true
  }'

Example Response

{
  "status": "OK",
  "session": {
    "handle": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "user123",
    "recipeUserId": "user123",
    "userDataInJWT": {
      "role": "admin",
      "email": "[e-mail]"
    },
    "tenantId": "public"
  },
  "accessToken": {
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiry": 1640000000000,
    "createdTime": 1639996400000
  },
  "refreshToken": {
    "token": "def456...",
    "expiry": 1648000000000,
    "createdTime": 1639996400000
  },
  "antiCsrfToken": "anti-csrf-token-value"
}

Implementation Details

Source Code Reference

Implemented in:

• API Handler: View source
• Session Logic: View source

Session Creation Process

1. Generate Session Handle - Creates a UUID and appends tenant ID if not default
2. Handle User ID Mapping - Resolves external user ID to SuperTokens user ID if mapping exists
3. Resolve Primary User - Determines primary user ID for linked accounts
4. Create Refresh Token - Generates opaque refresh token with optional anti-CSRF
5. Create Access Token - Generates JWT with user data and token hashes
6. Store in Database - Persists session data with hashed refresh token
7. Update Active Users - Records user activity timestamp

Token Expiry

Default token lifetimes (configurable in core config):

• Access Token: 1 hour (3600000 ms)
• Refresh Token: 100 days (8640000000 ms)

Security Considerations

Access Token Payload Size: Keep userDataInJWT minimal as it’s included in every request. Large payloads increase bandwidth and may exceed size limits.

User ID Mapping: If using external user ID mapping, provide the external user ID. The core will automatically resolve to the internal SuperTokens user ID.

Enable Anti-CSRF: Always enable anti-CSRF protection for browser-based applications to prevent cross-site request forgery attacks.

Error Responses

status · string

Error status code

message · string

Error description

Common Errors

• 400 Bad Request: Invalid userDataInJWT payload that exceeds size limits or contains invalid data
• 500 Internal Server Error: Database connection issues or internal processing errors

CDI Version Compatibility

• CDI < 2.21: Returns idRefreshToken in response
• CDI >= 2.21: idRefreshToken removed, useDynamicSigningKey parameter available
• CDI >= 3.0: tenantId included in session response
• CDI >= 4.0: recipeUserId included in session response