The branded SDK needs a session bound to the signed-in cardholder and their cardholder group so it can show the correct offers and balances. Use issuer registration, signed session requests and key rotation to establish that access through your backend. These SDK sessions are separate from the issuer API credential used for server-to-server requests.
The issuer authenticates the end user in its backend, then gives the SDK a short-lived session through an issuer-controlled proxy. The SDK does not authenticate users.
Production SDK integrations require signed JWT client assertions. The issuer proxy signs every widget-session mint request with its private key, and Percents verifies the assertion with the issuer's registered JWKS. Do not use a shared secret or issuer API token for this flow.
Issuer host app and browser
-> issuer proxy: opaque proxy session token
-> Percents: no issuer credential and no widget token
Issuer proxy
-> Percents: short-lived widget token bound to issuer, active cardholder and groupThe browser and hosted iframe must never receive an issuer-wide Percents API token or the Percents widget token. The opaque proxy session token is meaningful only to the issuer proxy.
- The issuer backend authenticates the current user and selects that user's active cardholder identity. Never use browser-supplied identities as the source of truth.
- The backend chooses either existing Percents cardholder and group IDs or issuer external IDs. The mint operation accepts exactly one of these choices.
- The issuer proxy signs a fresh assertion with the selected identity fields and sends it with the mint request.
- Percents verifies the JWT before any cardholder or group lookup or provisioning. It then checks issuer ownership and cardholder membership. The external-ID choice can create a missing cardholder or group, but never a card.
- Percents returns a widget token bound to the issuer, active cardholder and group. The proxy stores the token and identity mappings server-side and creates an opaque proxy session.
- The proxy returns only
widgetUrl,proxyApiBaseUrl,proxySessionTokenandexpiresAtto the SDK. Each proxied request must use the bound active cardholder and group.
Persist the issuer-user-to-cardholder and group mappings. Webhooks identify the group, while SDK requests are attributed to the active cardholder within it.
For the browser response, see the SDK Quickstart. For session boundaries, see SDK Security and Sessions.
The mint contract uses a signed JWT assertion to authenticate the issuer proxy. It proves control of the registered private key and binds the request to the selected identity.
Percents first resolves the issuer's enabled registration using iss and selects kid from that registration's trusted JWKS URL. Assertion-provided URLs never establish trust. Percents verifies the signature, algorithm, issuer, audience, timestamps and unique assertion ID before looking up or creating cardholders or groups.
Send the assertion to the session mint operation:
POST <percents-api-base-url>/api/v2/widget/session
Authorization: Bearer <signed-mint-assertion>
Content-Type: application/jsonChoose exactly one strict request shape. Do not mix Percents IDs with external IDs or add fields from the other shape.
For an existing cardholder and group:
{
"issuerId": "iss_00000000-0000-4000-8000-000000000001",
"cardholderId": "ch_00000000-0000-4000-8000-000000000004",
"chgId": "chg_00000000-0000-4000-8000-000000000002"
}For initialization using your own IDs:
{
"issuerId": "iss_00000000-0000-4000-8000-000000000001",
"externalCardholderId": "issuer-cardholder-001",
"externalCardholderGroupId": "issuer-group-001"
}Only externalCardholderGroupId is optional in the external-ID shape. Supply it to assign a new or unassigned cardholder to that group, creating the group when needed. Omit it to reuse the existing assignment or create a single-cardholder group whose externalId equals externalCardholderId. An already assigned cardholder cannot be moved to another group. Both identities must belong to the issuer, and the cardholder must belong to the selected group. See lazy provisioning.
<signed-mint-assertion> is an RS256 JSON Web Signature (JWS) carrying a JSON Web Token (JWT). Send it only from the issuer proxy to Percents.
| Location | Field | Required value |
|---|---|---|
| Protected header | alg | RS256. Other algorithms are rejected. |
| Protected header | kid | Nonempty key ID, at most 256 characters, selecting a unique RSA signing key in the registered JWKS. |
| JWT claim | iss | Exact Percents issuerId from onboarding, including iss_. Must equal the body's issuerId. |
| JWT claim, Percents-ID choice | cardholderId | Must exactly match the body. Do not include external identity claims. |
| JWT claim, Percents-ID choice | chgId | Must exactly match the body and contain the active cardholder. |
| JWT claim, external-ID choice | externalCardholderId | Must exactly match the body. Do not include Percents identity claims. |
| JWT claim, external-ID choice | externalCardholderGroupId | Optional. Its value and presence or absence must exactly match the body. |
| JWT claim | aud | Exact audience string registered for the issuer and environment. An array is not accepted. |
| JWT claim | iat | Integer Unix time in seconds, no later than now and less than 60 seconds old when verified. Keep backend clocks synchronized. |
| JWT claim | exp | Integer Unix time in seconds, later than iat and now, at most 60 seconds after iat. |
| JWT claim | jti | Fresh nonempty assertion ID, at most 256 characters. Used IDs cannot be reused within the issuer's validity window. |
These decoded examples show both choices. Generate current timestamps and a fresh jti for every request.
Percents-ID assertion:
{
"iss": "iss_00000000-0000-4000-8000-000000000001",
"cardholderId": "ch_00000000-0000-4000-8000-000000000004",
"chgId": "chg_00000000-0000-4000-8000-000000000002",
"aud": "percents-widget-mint",
"iat": 1730000000,
"exp": 1730000060,
"jti": "00000000-0000-4000-8000-000000000003"
}External-ID assertion for the request above:
{
"iss": "iss_00000000-0000-4000-8000-000000000001",
"externalCardholderId": "issuer-cardholder-001",
"externalCardholderGroupId": "issuer-group-001",
"aud": "percents-widget-mint",
"iat": 1730000000,
"exp": 1730000060,
"jti": "00000000-0000-4000-8000-000000000005"
}If the body omits externalCardholderGroupId, omit it from the assertion too. Use the audience supplied during onboarding. The signed assertion must fit within 8 KiB. Unsupported critical headers are rejected.
aud is the standard JWT audience claim defined in RFC 7519 section 4.1.3. It identifies the intended recipient of a token. In this flow, the recipient is the Percents SDK-session endpoint. The issuer, SDK and iframe are not the recipient.
Percents supplies the exact, environment-specific audience value during onboarding. The issuer proxy must include that exact value in every mint assertion, and Percents rejects an assertion with any other value. This prevents an assertion created for another API, customer integration, or environment from being accepted by the widget-session mint endpoint. This follows the JWT best practice to validate issuer and audience claims (RFC 8725 section 3.9).
- Percents supplies your exact
issuerIdand the expected audience for the integration environment. - Configure the issuer server to set JWT
issto that exactissuerId, includingiss_, and send the same ID in the mint request body. Generate and protect an RSA private key of at least 2048 bits in the issuer server, and publish its public key with a uniquekidat a stable HTTPS JWKS URL. - Give Percents that public JWKS URL. Percents persists one issuer-owned registration containing the trusted URL, expected audience and enabled state. New registrations start disabled. Coordinate enablement and signed-path validation with Percents. Your private key stays in your infrastructure.
- Authenticate your user, select one of the two identity choices, and sign a fresh assertion with your private key. Include the published
kidin the protected header and use the claims above. - Percents resolves the enabled registration from
iss, selects the public key usingkid, verifies the assertion and request scope before identity lookup or provisioning, then checks issuer ownership, cardholder membership and SDK access before issuing the scoped widget session.
Percents stores the issuer's trust configuration. Changes do not require a deployment. Coordinate JWKS URL or audience updates with Percents.
- Each new authentication reads the current enabled registration.
- Token headers such as
jkuandx5ucannot override the registered URL. Redirects are refused. - Disabling a registration blocks new sessions, including when keys are cached.
- Already-issued widget sessions remain bounded by their expiry and the issuer's SDK access gate.
Publish the new public key with a new kid before signing with it. Percents caches a successful JWKS response for five minutes. An unknown kid or signature mismatch can trigger one refresh, subject to a ten-second cooldown per URL. Simultaneous requests share the fetch. A cold-cache fetch counts as that request's refresh attempt. Coordinate the switch with the cooldown and keep the prior public key published until assertions signed with it have expired.
JWKS requests have these limits:
| Constraint | Limit |
|---|---|
| Timeout | Two seconds |
| Redirects | Refused |
| Response size | 64 KiB |
| Keys per response | 100 |
Use distinct, nonempty key IDs. Fresh cached keys may be used during a JWKS endpoint outage. A cold or expired cache requires a successful fetch.
A registered endpoint must use HTTPS in production. Updating the registered URL selects that endpoint for subsequent authentications.
The server-only response contains tokenType, accessToken, expiresAt, expiresInSeconds and the resolved cardholderId and chgId. It includes lazilyProvisionedAccounts only when the mint created a cardholder or group, with mappings only for those newly created accounts. No card is created or returned.
The widget token:
- Binds the issuer, active cardholder and group, and permits only widget-safe operations.
- Expires within 600 seconds.
- Cannot provision or manage cardholder groups.
Store the token and returned identities on the issuer server. Keep the browser bootstrap limited to its four fields.
Attribute each SDK request to the bound active cardholder. Reject identity mismatches, issuer ownership failures and revoked group membership. End the proxy session when membership or the authenticated user changes. A new login requires a new proxy session and widget token, even when the group is unchanged.
Widget activity must use the session's active cardholder. Never select another group member or use a browser-supplied cardholder ID.
Missing, unknown or disabled registrations, mismatched issuer scope, invalid claims/signatures, replayed assertions and unavailable verification reject the mint. Demo identity headers cannot authenticate this endpoint. There is no unsigned or shared-secret fallback. The issuer must also have SDK access enabled, and both the active cardholder and group must belong to that issuer, with valid membership between them.
For retries and troubleshooting:
- Use a fresh assertion, timestamps and
jtifor every retry, including after a lost response or failed mint. A nonce may already have been consumed before a later check fails. Never retry by reusing the same assertion. - After a key-rotation cooldown rejection, wait for the cooldown before retrying.
- For other failures, check the registered issuer/audience/URL, enablement, cardholder and group mappings and backend clock, then use the standard error identifier when contacting Percents support.
Do not log tokens or private keys.
- Keep issuer API tokens, signing keys, and widget tokens in server-side infrastructure only.
- Use an expiring, opaque proxy session token in the browser. Validate it on every proxy request.
- Allowlist only the widget routes the proxy needs. Do not turn the proxy into a general-purpose Percents API relay.
- Enforce the bound issuer, active cardholder and group on every proxied request. Keep identity fields and provisioning mappings out of browser-visible responses.
- Store proxy sessions and widget tokens in a shared, durable server-side store when using multiple proxy instances.
- Restrict browser origins and iframe framing with appropriate CORS and CSP
frame-ancestorsconfiguration.