Feature SSO Token

The Feature SSO Token is used by feature providers to onboard cardholders when a feature is enabled from within the mCards mobile app. It allows the mCards platform to securely pass cardholder context to a feature provider's embedded onboarding web application.

Purpose

When a cardholder enables a feature, mCards launches a feature provider-hosted onboarding web application. The feature provider must be able to:

Trust that the request originated from the mCards platform
Identify the cardholder
Complete feature onboarding securely

The Feature SSO Token solves this by providing a signed, short-lived user-context token at application launch time.

When the Token Is Issued

The Feature SSO Token is issued only during feature onboarding flows:

A cardholder selects or enables a feature in the mCards mobile app
The mobile app launches the feature provider's onboarding web application
mCards includes the Feature SSO Token with the onboarding request
The feature provider validates the token and completes onboarding

The token is scoped specifically to the feature onboarding context and is not reused for other interactions.

How the Token Is Delivered

The token is included in the Authorization header as a Bearer token
The token is a JSON Web Token (JWT)
The token is intended for immediate validation and use

What the Token Represents

The Feature SSO Token represents:

Represents	Does NOT Represent
A specific cardholder	API access rights
A specific feature onboarding session	Long-term user identity
A trusted request from the mCards platform	Permission to call mCards APIs

Token Structure

The Feature SSO Token is a signed JWT with claims describing the onboarding context:

Claim	Description
`iss`	Identifies mCards as the issuing platform
`aud`	Identifies the feature provider (configured per feature)
`iat`	Token issue time (Unix timestamp)
`exp`	Token expiration — 5 minutes after issue
`consumer_id`	The cardholder's UUID
`phone_number`	The cardholder's phone number
`cardholder_card.cardholder_card_uuid`	UUID of the cardholder's card
`distributor_card.distributor_card_uuid`	UUID of the card program

Depending on the feature configuration, additional optional claims may be included:

Optional Claim	Included When
`full_name`, `first_name`, `last_name`	Feature is configured to include cardholder name
`email`	Feature is configured to include cardholder email
`date_of_birth`	Feature is configured to include date of birth
`address`	Feature is configured to include cardholder address
`location`	Feature is configured to include location data

Sample Payload

{
  "consumer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "phone_number": "+15551234567",
  "cardholder_card": {
    "cardholder_card_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  },
  "distributor_card": {
    "distributor_card_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  },
  "full_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "exp": 1716000600,
  "iss": "mcards",
  "iat": 1716000300,
  "aud": "your-feature-identifier"
}

Note: Optional claims (full_name, email, etc.) appear only when the feature is configured to include them. Your token may contain a subset of these fields.

Token Validation

Feature providers must validate the Feature SSO Token before using it:

Verify the token signature using public keys from the mCards JWKS endpoint
Confirm the issuer matches mCards
Check expiration to ensure the token has not expired
Verify the audience matches the feature provider

Signature Verification

Tokens are digitally signed by mCards
Feature providers validate the signature using public keys published by mCards
Public keys are retrieved from the mCards JSON Web Key Set (JWKS) endpoint

Trust Boundaries

mCards Responsibilities

Issue Feature SSO Tokens at the correct point in the onboarding flow
Sign tokens using platform-controlled private keys
Publish public keys for token verification

Feature Provider Responsibilities

Validate the Feature SSO Token before using it
Reject requests with invalid, expired, or improperly scoped tokens
Protect cardholder data obtained during onboarding
Use the token only within the onboarding session

Common Mistakes to Avoid

Treating the Feature SSO Token as an API credential
Reusing the token outside the onboarding session
Skipping token signature validation
Ignoring token expiration
Assuming tokens are interchangeable across environments (sandbox vs production)

Related Guides

Embedded Partner Web Applications — The onboarding pattern this token supports
Tokens for Embedded Web Applications — Shared token model
Payments User Token — The token used for payment gateway onboarding