JWT Payload

Cognito issues two types of JWT tokens: an Identity Token (used to identify the user) and an Access Token (used to authorize API access). This document describes their claim structures.

Note: This document reflects the intended token structure while Cognito integration is in progress. Confirm all claims against live system behavior.

Identity Token

The Identity Token identifies the user and includes custom attributes.

Key Claims

Claim	Description
sub	Unique user ID in the User Pool
email	User’s email address
email_verified	Whether the email has been verified
cognito:username	Internal Cognito username
custom:tenant	Tenant ID: <tenant-name>::<tenant-uuid>
custom:role	User role: public, lite, subscriber, admin, or system
aud	Client ID (audience)
iss	Issuer URL: https://cognito-idp.<region>.amazonaws.com/<user-pool-id>
exp	Expiry timestamp
iat	Issued-at timestamp
auth_time	Authentication timestamp
identities	Federated identity metadata (e.g., Google SSO)

Example

{
  "sub": "248289dc-...-f2f44a",
  "email_verified": true,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "custom:tenant": "acme-corp::1fa48bf2-3ef9-4d08-8858-29e71504a1ed",
  "custom:role": "subscriber",
  "cognito:username": "janedoe",
  "aud": "client-app-id",
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123",
  "exp": 1712608972,
  "iat": 1712605372,
  "auth_time": 1712605370
}

Access Token

The Access Token authorizes calls to protected API endpoints. It does not include user profile attributes by default.

Key Claims

Claim	Description
token_use	"access" — identifies the token type
scope	Space-separated OAuth2 scopes granted
client_id	App client that requested the token
username	Cognito username
iss	Issuer URL
exp, iat	Expiry and issued-at timestamps
jti	Unique token identifier

Example

{
  "sub": "248289dc-...-f2f44a",
  "token_use": "access",
  "scope": "openid profile email aws.cognito.signin.user.admin",
  "auth_time": 1712605372,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123",
  "exp": 1712608972,
  "iat": 1712605372,
  "jti": "token-id",
  "client_id": "client-app-id",
  "username": "janedoe"
}

Custom Attribute Constraints

Cognito custom attributes support only string values (max 2048 characters). JSON objects, arrays, and nested structures are not allowed. Multi-valued attributes must be encoded as delimited strings.