Scopes & Claims

Control what data your app can access. Request only what you need.

Available Scopes

Scope	Claims Returned	Description
openid	`sub` `iss` `aud` `exp` `iat` `auth_time`	Required. Returns the user's unique subject ID.
profile	`name` `picture` `updated_at`	User's display name and avatar
email	`email` `email_verified`	Email address and verification status
wallet	`wallet_address`	User's EVM wallet address
offline_access	none — grants refresh token	Enables silent token renewal via refresh tokens
payments	none — grants charge ability	Allows the app to charge the user's stored payment method via Stripe
subscription	`subscription`	Returns the user's active subscription plan, status, amount, and billing interval

Example ID Token Claims

With scope=openid profile email wallet:

{
  "iss": "https://id.networkcoin.ai",
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "aud": "your-client-id",
  "iat": 1700000000,
  "exp": 1700003600,
  "auth_time": 1700000000,
  "name": "Alice",
  "email": "alice@example.com",
  "email_verified": true,
  "picture": "https://ui-avatars.com/api/?name=Alice",
  "wallet_address": "0x742d35Cc6634C0532925a3b..."
}

UserInfo Response

The /oauth/userinfo endpoint returns claims fetched fresh from the database. With subscription scope, it also returns the user's active plan:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alice",
  "email": "alice@example.com",
  "email_verified": true,
  "picture": "https://ui-avatars.com/api/?name=Alice",
  "wallet_address": "0x742d35Cc6634C0532925a3b...",
  "subscription": {
    "plan": "Business",
    "status": "active",
    "amount": 7900,
    "interval": "month",
    "current_period_end": "2026-05-02T00:00:00.000Z",
    "cancelled_at": null
  }
}

If no active subscription exists, subscription will be null.

Best Practices

Always request openid — it's required for OIDC
Only request scopes you actually use — users trust apps that ask for less
Use offline_access for background token renewal and to track connected users in the Console
The email scope is recommended for account matching and user contact
Use subscription to gate features based on the user's active plan (Personal, Business, Enterprise, etc.)