JWT Claims Reference

AuthOS uses JSON Web Tokens (JWT) for authentication. This reference documents all JWT claims and token types.

Token Types

Access Token Claims

Standard access tokens contain these claims:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "exp": 1705401600,
  "iat": 1705315200,
  "nbf": 1705315200,
  "jti": "unique-token-id",
  "org": "acme-corp",
  "service": "main-app",
  "is_platform_owner": false
}

Claim Details

Token Contexts

Platform Context Token

Token without organization or service claims. Used for platform-level operations.

{
  "sub": "user-uuid",
  "email": "admin@example.com",
  "org": "",
  "service": "",
  "is_platform_owner": true
}

Use Cases:

• Platform owner administration
• User profile management before org selection
• Cross-organization operations

Organization Context Token

Token with organization but no service. Used for org administration.

{
  "sub": "user-uuid",
  "email": "admin@acme.com",
  "org": "acme-corp",
  "service": "",
  "is_platform_owner": false
}

Use Cases:

• Organization settings management
• Member management
• Service configuration

Service Context Token

Token with both organization and service. Standard end-user token.

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "org": "acme-corp",
  "service": "main-app",
  "is_platform_owner": false
}

Use Cases:

• End-user authentication
• Service-specific API calls
• Provider token access

Pre-auth Token

Issued when MFA verification is required before completing authentication.

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "exp": 1705315800,
  "iat": 1705315200,
  "type": "preauth",
  "org": "acme-corp",
  "service": "main-app"
}

Pre-auth Specific Claims

Notes:

• Short-lived (10 minutes)
• Must be exchanged for full access token via MFA verification
• Cannot be used for API access

Token Validation

JWKS Endpoint

Retrieve public keys for token verification:

GET /.well-known/jwks.json

Response:

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "kid": "sso-key-2025-01-01",
      "n": "base64url-encoded-modulus",
      "e": "AQAB"
    }
  ]
}

Validation Steps

1. Parse the JWT - Extract header, payload, signature
2. Verify signature - Use public key from JWKS endpoint
3. Check expiration - Ensure exp > current time
4. Check not-before - Ensure nbf <= current time
5. Verify issuer - Match expected issuer (if configured)
6. Check claims - Validate org and service match expected values

Example: Node.js Validation

const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const client = jwksClient({
  jwksUri: 'https://sso.example.com/.well-known/jwks.json'
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}

function verifyToken(token) {
  return new Promise((resolve, reject) => {
    jwt.verify(token, getKey, {
      algorithms: ['RS256']
    }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded);
    });
  });
}

Refresh Tokens

Refresh tokens are opaque UUIDs stored in the database.

Refresh Flow

POST /api/auth/refresh
Content-Type: application/json

{
  "refresh_token": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "660f9500-f30c-52e5-b827-557766551111",
  "expires_in": 86400
}

Security Notes:

• Refresh token is rotated on each use
• Old refresh token is invalidated
• Store refresh tokens securely (httpOnly cookies recommended)

Session Management

Session Invalidation

Sessions can be invalidated via:

1. Logout - Revokes current session
2. Password change - Revokes all other sessions
3. MFA disable - Revokes all sessions
4. Admin force-logout - Revokes specific user sessions

Checking Session Validity

The jti claim can be checked against the session store:

async function isSessionValid(decodedToken) {
  const session = await sessionStore.findByJti(decodedToken.jti);
  return session && !session.revoked_at;
}