Guides
Start typing to search…

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.

This guide is the authoritative reference for the Feature SSO Token and describes when it is issued, how it is delivered, what it represents, and how feature providers are expected to validate and use it.

Purpose of the Feature SSO Token

When a cardholder enables a feature, mCards launches a feature provider–hosted onboarding web application. At that moment, 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 problem by providing a signed, short-lived user-context token at application launch time.

When the Feature SSO Token Is Issued

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

At a high level:

  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 Feature SSO Token is delivered to the feature provider’s onboarding web application as part of the initial request.

  • 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

The delivery mechanism ensures that cardholder context is passed securely without exposing API credentials or internal platform identifiers.

What the Feature SSO Token Represents

Conceptually, the Feature SSO Token represents:

  • A specific cardholder
  • A specific feature onboarding session
  • A trusted request initiated by the mCards platform

The token does not represent:

  • API access rights
  • Long-term user identity
  • Permission to call mCards APIs
  • Authorization to perform transactions

Those concerns are handled separately through API authentication and transaction processing.

Token Structure (Conceptual)

The Feature SSO Token is a signed JWT that includes claims describing the onboarding context.

At a conceptual level, the token includes:

  • Issuer
    Identifies mCards as the issuing platform

  • Audience
    Identifies the feature provider

  • Expiration
    Enforces short token lifetime

  • Cardholder context
    Identifiers required to associate the onboarding session with a cardholder

The exact claim names and values are implementation details, but feature providers should treat the token as opaque beyond the claims they are instructed to consume.

Token Validation

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

At a minimum, validation includes:

  1. Verifying the token signature
  2. Confirming the token was issued by mCards
  3. Ensuring the token has not expired
  4. Ensuring the token 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

Successful validation establishes trust between the feature provider’s onboarding application and the mCards platform.

Trust Boundaries and Responsibilities

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

mCards does not manage feature provider onboarding logic, and feature providers do not have access to mCards mobile app internals.

Relationship to Embedded Partner Web Applications

The Feature SSO Token is an implementation of the Embedded Partner Web Application pattern.

  • The embedded web application provides the onboarding experience
  • The Feature SSO Token provides secure cardholder context

Other partner types may use different tokens, but the overall pattern remains consistent.

Relationship to APIs

The Feature SSO Token is not used for API authentication.

Feature providers must use standard mCards API authentication mechanisms when calling APIs. The Feature SSO Token:

  • Is limited to embedded onboarding
  • Does not grant API access
  • Should never be used in backend API requests

Common Implementation Mistakes

Feature providers should avoid the following mistakes:

  • 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

Related Guides

  • Embedded Partner Web Applications
    Describes the embedded onboarding pattern used by feature providers.

  • Tokens for Embedded Web Applications
    Describes shared properties of user-context tokens.

  • Payments User Token
    Describes the token used for payment gateway onboarding.

Next step

Continue to Payments User Token to see how embedded onboarding and user-context tokens are used by payment gateway providers.

Updated about 2 months ago