Skip to main content

Token Types

epilot uses three token types for authentication. Choose the right one for your integration:

Token Comparison​

OAuth 2.0 TokenAccess TokenPublishable Token
Lifetime60 minutesConfigurable expiry, up to 365 days (valid until revoked if unset)Long-lived (no expiry)
Use caseInteractive user sessionsServer-side API integrationsClient-side public apps (journeys, portals)
FormatJWT (Cognito-issued)JWT (epilot-issued)JWT (epilot-issued, public key)
RefreshVia refresh tokenNot neededNot needed
ScopeFull user permissionsScoped to assigned rolesLimited to public API access
SecurityKeep confidentialKeep confidentialSafe for client-side use

OAuth 2.0 Tokens​

epilot uses Amazon Cognito User Pools as the OAuth 2.0 identity provider.

Token Set​

On successful authentication, Cognito issues three tokens:

  • ID Token — Contains user identity claims (sub, email, custom:org_id). epilot APIs use this token for authorization.
  • Access Token — Standard Cognito access token for the user pool.
  • Refresh Token — Obtains new ID/access tokens without re-authenticating.

Lifetime​

OAuth tokens expire after 60 minutes. Use the refresh token to obtain new tokens transparently.

tip

OAuth tokens suit interactive user sessions. For API integrations, use Access Tokens instead.

Access Tokens​

Access Tokens are JWTs for server-side integrations — the recommended authentication method for backend systems, scripts, and third-party applications. You can set an expiry when creating a token; tokens created without one stay valid until revoked. See Access Tokens for full management details.

How They Work​

The epilot Access Token service issues JWTs with claims compatible with Cognito-issued tokens, so all epilot APIs accept them seamlessly via the standard Authorization header.

Authorization: Bearer <your-access-token>

Creating Access Tokens​

Create tokens in the epilot portal under Settings > Access Tokens, or programmatically via the Access Token API:

create-access-token.ts
import { authorize, getClient } from '@epilot/sdk/access-token';

const accessTokenClient = getClient();
authorize(accessTokenClient, cognitoIdToken);

const { data } = await accessTokenClient.createAccessToken(null, {
  name: 'SAP Integration',
  assume_roles: ['123:sap_integration_role'],
  expires_in: '30d', // optional expiry — seconds or a duration string
});

// data.access_token contains the token — save it securely

Role Assignment​

Scope each Access Token to specific roles via assume_roles. If omitted, the token inherits the creating user's roles.

Role assignment
{
  "assume_roles": ["123:sap_integration_role"]
}

Token Expiry​

Set an optional expiry when creating a token via the expires_in parameter — either a number of seconds (e.g. 3600) or a duration string with time units (e.g. '10h', '7d', '2 days'). Expired tokens are rejected by the API Gateway authorizer like any other expired JWT.

  • Standard Access Tokens (token_type: api, the default) accept an expiry between 30 seconds and 365 days.
  • Other token types created with an explicit expires_in (e.g. app tokens) are capped at 7 days, since they're ephemeral and not manageable from the token list.

If expires_in is omitted, the token does not expire and remains valid until revoked.

Access Tokens created with an expiry are still persisted, listed, and revocable like any other token — the create response includes an expires_at timestamp, and the token disappears from the list once it expires.

warning

Creating access tokens requires the token:create permission. The generated token is shown only once and cannot be recovered.

Revoking Access Tokens​

Revoke tokens from the management UI or via the API:

Revoke an access token
DELETE /v1/access-tokens/{id}

Revoked tokens are immediately invalidated.

Publishable Tokens​

Publishable Tokens are safe to embed in client-side code for public-facing applications like journeys and customer portals.

Characteristics​

  • Limited scope — Only grants access to public-facing APIs (submissions, product catalog, file uploads)
  • Tenant identity — Encodes the organization ID, eliminating the need for x-epilot-org-id headers
  • Separate signing key — Verified via a dedicated public JWKS endpoint, separate from Access Token keys
  • Revocable — Can be rotated or revoked from the Access Token management UI

Usage​

Pass Publishable Tokens as a bearer token in the Authorization header:

Authorization: Bearer <publishable-token>

Journeys and portals use the Publishable Token from their configuration automatically. You typically don't need to manage these tokens manually.

JWT Structure​

All token types use JWT (JSON Web Token) format, signed with RS256.

OAuth 2.0 ID Token Claims​

ClaimDescription
subCognito user ID
emailUser's email address
custom:org_idOrganization ID
issCognito User Pool issuer URL (https://cognito-idp.<region>.amazonaws.com/<pool-id>)
expExpiration timestamp

Access Token Claims​

ClaimDescription
token_idUnique token identifier (e.g., api_5ZugdRXasLfWBypHi93Fk)
token_nameHuman-readable token name
org_idOrganization ID
user_idUser identifier (same as token_id for API tokens)
token_typeToken type: api, journey, portal, assume, app
assume_rolesList of role IDs (e.g., ["123:owner"])
issAccess Token service issuer URL
iatIssued-at timestamp
expExpiration timestamp (present when the token was created with an expiry)

Token Verification​

The epilot API Gateway authorizer verifies all tokens automatically using JWKS (JSON Web Key Set) endpoints:

Token TypeJWKS Endpoint
OAuth (Cognito)https://cognito-idp.<region>.amazonaws.com/<pool-id>/.well-known/jwks.json
Access Token/v1/access-tokens/.well-known/jwks.json
Publishable Token/v1/access-tokens/public/.well-known/jwks.json

Choosing a Token Type​

ScenarioToken TypeAction
Backend integrationAccess TokenCreate under Settings > Access Tokens with scoped roles
Interactive user sessionsOAuth TokenIssued automatically on portal login
Embedding a journey or portalPublishable TokenConfigured automatically — no action needed

See Also​