Tokens for Embedded Web Applications

When mCards launches an embedded partner onboarding application, it must securely convey who the cardholder is and why the application is being launched. This is accomplished using user-context tokens issued by the mCards platform.

This guide describes the shared token model used by embedded partner web applications and how partners should reason about these tokens at a conceptual level.

Why Tokens Are Required

Embedded partner web applications are hosted and operated outside of the mCards platform. When the mCards mobile app navigates a cardholder to a partner onboarding application, the partner must be able to:

Identify the cardholder
Trust that the request originated from mCards
Understand the onboarding context

User-context tokens solve this problem by allowing mCards to securely pass cardholder context to the partner at application launch time.

What These Tokens Represent

Tokens used for embedded partner web applications represent:

A specific cardholder
A specific onboarding context
A trusted request originating from the mCards platform

These tokens are:

Issued by mCards
Digitally signed
Intended for single-purpose use during onboarding flows

They are not general-purpose identity tokens and should not be reused beyond the onboarding context in which they are issued.

How Tokens Are Used

At a high level, the token flow works as follows:

A cardholder initiates an onboarding action in the mCards mobile app
mCards launches the partner’s onboarding web application
A user-context token is provided to the partner application as part of the request
The partner application validates the token
The partner uses the token claims to:
- Identify the cardholder
- Complete onboarding

The exact claims and audience differ depending on the integration type, but the usage model remains consistent.

Token Properties

All user-context tokens for embedded partner web applications share the following properties:

Short-lived
Tokens are valid only for a limited time and are intended for immediate use.
Signed by mCards
Tokens are digitally signed to prevent tampering.
Verifiable by Partners
Partners validate tokens using public keys provided by mCards.
Context-specific
Tokens are issued for a specific onboarding flow and partner type.

Trust and Verification Model

Partners are responsible for verifying tokens before using them.

At a conceptual level, verification includes:

Confirming the token was signed by mCards
Ensuring the token has not expired
Ensuring the token audience matches the partner application

Token verification establishes trust between mCards and the partner application, not between mCards and backend APIs.

What These Tokens Are Not

It is important to distinguish user-context tokens from other security mechanisms used by the mCards platform.

These tokens are not:

API authentication credentials
Replacements for API HMAC keys and secrets
Long-lived identity tokens
Tokens that grant direct access to mCards APIs

API authentication is handled separately and is described in the Common API Concepts guide.

Token Types Used by mCards

The mCards platform currently issues two types of user-context tokens for embedded partner onboarding.

Feature SSO Token

Used when onboarding a cardholder with a feature provider.

This token enables feature providers to identify the cardholder and complete feature enrollment during embedded onboarding.

Details are covered in the Feature SSO Token guide.

Payments User Token

Used when onboarding a cardholder with a payment gateway provider.

This token enables payment gateways to onboard cardholders and create payment accounts that participate in transaction processing.

Details are covered in the Payments User Token guide.

Related Guides

Feature SSO Token
Feature-specific token usage and onboarding flow.
Payments User Token
Payment gateway–specific token usage and onboarding flow.
Embedded Partner Web Applications
Overview of the embedded onboarding pattern.

Next step

Continue to Feature SSO Token to see how user-context tokens are applied in feature onboarding flows.