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:

1. A cardholder selects or enables a feature in the mCards mobile app
2. The mobile app launches the feature provider's onboarding web application
3. mCards includes the Feature SSO Token with the onboarding request
4. 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 a JSON Web Token (JWT)
• It is appended to the onboarding web application's launch URL as the fm_token query parameter
• The token is intended for immediate validation and use

Note: When mCards calls a feature provider's own API (provider authorization callbacks), a
separate provider token is sent in the X-FM-Authorization-JWT header. Neither token is sent as an
Authorization: Bearer credential.

What the Token Represents

The Feature SSO Token represents:

Token Structure

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

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

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": "https://fm-uat.mcards.com/api/features_marketplace/",
  "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:

1. Verify the token signature using public keys from the mCards JWKS endpoint (see below)
2. Confirm the issuer matches the exact iss string for the environment you integrate with (see Issuer values)
3. Check expiration to ensure the token has not expired
4. Verify the audience matches the feature provider

Issuer values

The iss claim is the environment's Features Marketplace base URL, including the trailing slash:

The issuer host (fm.mcards.com / fm-uat.mcards.com) is the marketplace host alias and is
intentionally different from the host serving the JWKS URLs below; both resolve to the same platform.
Pin the issuer per environment — do not accept any *.mcards.com host.

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

JWKS Endpoints

• Tokens are signed with RS256; select the key whose kid matches the token header.
• Cache the key set (1–2 hours) and refetch when an unknown kid appears.
• Each environment publishes its own key set — sandbox tokens do not validate against production keys.
• Expected claims: iss is the environment issuer URL above, aud is your feature identifier.

If you prefer OpenID Connect discovery to a hardcoded URL, fetch
/api/features_marketplace/.well-known/openid-configuration on the same host and use its jwks_uri.
That field may name the marketplace host alias (fm.mcards.com / fm-uat.mcards.com), which serves the
same key set as the URLs above.

A feature-scoped key set is also available at
/api/features_marketplace/{marketer_feature_uuid}/.well-known/jwks.json if you want to restrict
verification to the keys for a single feature.

See API Authentication and Credentials for a worked validation example.

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