Feature Flags

Control access to functionality based on plans. Define features, map them to plans, and your users automatically get the right entitlements — embedded in the JWT for zero-latency client-side checks.

How it works

1. Define features in your project (e.g. analytics, max_seats)
2. Map features to plans — each plan specifies which features it includes
3. Assign a plan to a user (via payment or manually)
4. On next token issue, the user's JWT includes a features field with their resolved entitlements
5. Optionally override per user — grant or revoke features regardless of plan

Feature types

JWT structure

Features are resolved at token issue time and included alongside custom_claims:

{
  "sub": "user-id",
  "email": "user@example.com",
  "custom_claims": { "plan": "pro" },
  "features": {
    "analytics": true,
    "api_access": true,
    "max_seats": 5
  },
  "iss": "auth.astapa.com",
  "exp": 1234567890
}

Resolution logic

Features are resolved in this order:

1. Read the user's plan claim
2. Look up that plan's features JSON
3. Apply per-user overrides (grant or revoke)
4. Return merged result as features in JWT

Client-side usage

Decode the JWT and read the features object:

// After decoding the access token
const { features } = decodedToken;

if (features.analytics) {
  // Show analytics dashboard
}

if (features.max_seats && currentSeats >= features.max_seats) {
  // Block adding more seats
}

Server-side check API

For server-side checks without decoding the JWT, use the check endpoint:

POST /api/platform/features/check
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "end_user_id": "user-id",
  "feature_key": "analytics"
}

Response:

{
  "has_feature": true,
  "value": true
}

Management API

Limits

• Maximum 50 features per project
• Feature keys: 1-64 characters, lowercase alphanumeric with hyphens or underscores
• Features are resolved fresh on each token issue (no caching delay)