Tokens & Sessions - AgentFront

FrontMCP provides flexible token and session management with support for both stateful and stateless patterns.

Token Types

Token	Purpose	Lifetime	Storage
Access Token	API authorization	1 hour (default)	Client-side (JWT)
Refresh Token	Obtain new access tokens	30 days (default)	Server-side
Authorization Code	OAuth flow exchange	60 seconds	Server-side, single-use
Session Token	Track user session	Configurable	Depends on mode

Session Modes

FrontMCP supports two session management strategies:

Stateful Sessions

Tokens stored server-side. Clients hold lightweight references.Pros:

Silent token refresh
Revocation without client update
Secure token storage

Cons:

Requires shared storage (Redis)
State management complexity

Stateless Sessions

All data embedded in JWT. No server-side storage.Pros:

Horizontally scalable
No shared state
Simple architecture

Cons:

No silent refresh
Larger token size
Can’t revoke without expiry

Stateful Session Configuration

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'local',
    tokenStorage: {
      redis: {
        host: 'localhost',
        port: 6379,
        keyPrefix: 'myapp:auth:',
      },
    },
  },
})
export class Server {}

Stateless Session Configuration

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'local',
  },
})
export class Server {}

Stateful sessions require shared storage when running multiple server instances. Without Redis, each instance maintains its own session state.

Token Storage

In-Memory (Development)

tokenStorage: 'memory'

In-memory storage loses all data on restart. Use only for development.

Redis (Production)

tokenStorage: {
  redis: {
    host: 'redis.example.com',
    port: 6379,
    password: process.env.REDIS_PASSWORD,
    keyPrefix: 'auth:',
    tls: true,
  },
}

Storage Contents

Key Pattern	Data	TTL
`{prefix}pending:{id}`	Pending authorization	10 minutes
`{prefix}code:{code}`	Authorization code	60 seconds
`{prefix}refresh:{token}`	Refresh token	30 days
`{prefix}session:{id}`	Session data	Configurable

OrchestratedTokenStore Interface

When using local or remote mode with federated authentication, FrontMCP stores provider tokens using the OrchestratedTokenStore interface.

Interface Methods

Method	Description
`storeTokens(authorizationId, providerId, tokens)`	Store tokens for a provider
`getTokens(authorizationId, providerId)`	Retrieve tokens for a provider
`deleteTokens(authorizationId, providerId)`	Delete tokens for a provider
`getProviderIds(authorizationId)`	Get all provider IDs with stored tokens
`migrateTokens(fromAuthId, toAuthId)`	Migrate tokens between authorization IDs

Token Migration

The migrateTokens() method is used internally during federated auth completion to transfer tokens from a pending authorization ID to the final authorization ID:

import { InMemoryOrchestratedTokenStore } from '@frontmcp/auth';

const tokenStore = new InMemoryOrchestratedTokenStore();

// During federated auth, tokens are stored with pending ID
await tokenStore.storeTokens('pending:abc123', 'github', {
  accessToken: 'gho_xxx',
  refreshToken: 'ghr_xxx',
});

// After JWT issuance, tokens are migrated to real auth ID
await tokenStore.migrateTokens('pending:abc123', 'user:real-auth-id');

// Query which providers have tokens
const providerIds = await tokenStore.getProviderIds('user:real-auth-id');
// => ['github']

migrateTokens() is called automatically during the OAuth token exchange flow when completing federated authentication.

Token Lifetimes

FrontMCP uses default token lifetimes:

Token Type	Default Lifetime
Access Token	1 hour
Refresh Token	30 days
Authorization Code	60 seconds

Token Refresh Configuration

auth: {
  mode: 'local',
  refresh: {
    enabled: true,      // Enable automatic token refresh
    skewSeconds: 60,    // Refresh 60s before expiry
  },
}

Token lifetimes are currently set at the server level. Refresh tokens are rotated on each use per OAuth 2.1 best practices.

Token Refresh Flow

Refresh tokens are rotated on each use (OAuth 2.1 best practice):

JWT Structure

Access tokens are JWTs with standard claims:

{
  "header": {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "key-id-123"
  },
  "payload": {
    "sub": "user-uuid",
    "iss": "https://api.myservice.com",
    "aud": "https://api.myservice.com",
    "exp": 1234567890,
    "iat": 1234567800,
    "jti": "unique-token-id",
    "scope": "read write",
    "email": "user@example.com"
  }
}

Custom Claims

Custom claims are sourced from the upstream identity provider (or the in-tree IdP for local mode) — FrontMCP does not mint extra claims. Configure your IdP to include the claims you need (roles, tenant ID, etc.) and then read them via this.context.authInfo?.user (raw) or this.auth.claims (typed) inside tools, resources, prompts, and agents.

Enable consent to let users select granted permissions:

auth: {
  mode: 'local',
  consent: { enabled: true },
}

User authenticates
FrontMCP displays available tools/resources/prompts
User selects which to grant
Access token includes only selected scopes

Tool-Level Scopes

@Tool({
  name: 'send_message',
  description: 'Send a message',
  scopes: ['messages:write'], // Required scope
})
export class SendMessageTool {
  async execute(ctx: ToolContext) {
    // Only callable if token has messages:write scope
  }
}

JWKS Management

FrontMCP manages cryptographic keys for token signing:

Auto-Generated Keys

By default, keys are auto-generated at startup:

auth: {
  mode: 'local',
  // Keys auto-generated
}

Auto-generated keys are lost on restart. Tokens signed with old keys become invalid.

Persistent Keys

Provide keys for stable token validation across restarts:

auth: {
  mode: 'local',
  local: {
    signKey: {
      kty: 'RSA',
      // ... full JWK
    },
    jwks: {
      keys: [/* public keys */],
    },
  },
}

Key Rotation

For production, perform key rotation by deploying a new build with an updated signKey while keeping the previous keys in jwks until in-flight tokens have expired:

auth: {
  mode: 'local',
  local: {
    signKey: currentPrivateKey,
    jwks: { keys: [currentPublicKey, previousPublicKey] }, // publish ONLY public keys for verification
    issuer: 'https://your-server.example.com',
  },
}

signKey holds the private signing material; jwks is the public key set published at /.well-known/jwks.json for clients to verify tokens. Never put private JWKs into jwks — doing so exposes the private key.

Token Verification

Verification Flow

Verification Options

auth: {
  mode: 'transparent',
  provider: 'https://auth.example.com',
  expectedAudience: 'https://api.myservice.com',
  requiredScopes: ['openid', 'profile'],
}

Error Responses

Token-related errors follow OAuth 2.0 error format:

Error	HTTP Status	Description
`invalid_token`	401	Token expired, malformed, or invalid signature
`insufficient_scope`	403	Token missing required scopes
`invalid_request`	400	Malformed token request
`invalid_grant`	400	Invalid authorization code or refresh token

Example Error Response

{
  "error": "invalid_token",
  "error_description": "Token has expired",
  "error_uri": "https://tools.ietf.org/html/rfc6750#section-3.1"
}

Next Steps

Authorization Modes

Choose the right auth mode for your use case

Progressive Authorization

Implement incremental app authorization

Production Checklist

Security requirements for deployment

Remote OAuth

Connect to external identity providers

​Token Types

​Session Modes

Stateful Sessions

Stateless Sessions

​Stateful Session Configuration

​Stateless Session Configuration

​Token Storage

​In-Memory (Development)

​Redis (Production)

​Storage Contents

​OrchestratedTokenStore Interface

​Interface Methods

​Token Migration

​Token Lifetimes

​Token Refresh Configuration

​Token Refresh Flow

​JWT Structure

​Custom Claims

​Consent & Scopes

​How Consent Works

​Tool-Level Scopes

​JWKS Management

​Auto-Generated Keys

​Persistent Keys

​Key Rotation

​Token Verification

​Verification Flow

​Verification Options

​Error Responses

​Example Error Response

​Next Steps

Authorization Modes

Progressive Authorization

Production Checklist

Remote OAuth

Token Types

Session Modes

Stateful Session Configuration

Stateless Session Configuration

Token Storage

In-Memory (Development)

Redis (Production)

Storage Contents

OrchestratedTokenStore Interface

Interface Methods

Token Migration

Token Lifetimes

Token Refresh Configuration

Token Refresh Flow

JWT Structure

Custom Claims

Consent & Scopes

How Consent Works

Tool-Level Scopes

JWKS Management

Auto-Generated Keys

Persistent Keys

Key Rotation

Token Verification

Verification Flow

Verification Options

Error Responses

Example Error Response

Next Steps