{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/auth-security/sdk-auth","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"SDK Authentication","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"sdk-authentication","__idx":0},"children":["SDK Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK does not authenticate an end user itself. The issuer authenticates its user in its own backend, then gives the SDK a short-lived session through an issuer-controlled proxy."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Production SDK integrations use signed JWT client assertions. The issuer proxy signs every widget-session mint request with its private key, and Percents verifies that assertion with the issuer's registered JWKS. This is the required production authentication method; do not use a shared secret or issuer API token for this flow."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"trust-boundaries","__idx":1},"children":["Trust Boundaries"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Issuer host app and browser\n -> issuer proxy: opaque proxy session token\n -> Percents: no issuer credential and no widget token\n\nIssuer proxy\n -> Percents: short-lived, CHG-scoped widget token\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The 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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"session-flow","__idx":2},"children":["Session Flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The issuer backend authenticates the current user with its existing identity system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The issuer backend resolves that user or business to a persisted Percents cardholder group (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]},"). Do not accept a client-side-supplied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The issuer proxy obtains a short-lived widget token from Percents, scoped to that CHG, and stores it server-side."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The proxy creates an opaque, expiring proxy session and returns its token, the proxy API URL, and the widget URL to the SDK."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The hosted iframe sends its requests to the issuer proxy with the proxy-session token. The proxy validates the session, forwards only widget-allowed operations with the scoped widget token, and removes server-only data from responses."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Persist the issuer user/business-to-CHG mapping. Percents webhooks identify the CHG, so the issuer needs that durable mapping to route follow-up work or notifications correctly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For integration setup and the session response shape, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/embedded-widget/quickstart"},"children":["SDK Quickstart"]},". For iframe message and session boundaries, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/embedded-widget/security-sessions"},"children":["SDK Security and Sessions"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"production-mint-authentication","__idx":3},"children":["Production Mint Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The issuer proxy authenticates itself to Percents by sending a signed JWT assertion with every widget-session mint request. The assertion is a short-lived proof that the issuer proxy controls its registered private key and is authorized to mint a session for one cardholder group."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication-flow","__idx":4},"children":["Authentication Flow"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant Browser as Issuer host app and browser\n participant Proxy as Issuer proxy\n participant Percents as Percents API\n participant JWKS as Issuer JWKS endpoint\n participant Iframe as Percents iframe\n\n Browser->>Proxy: Request widget proxy session using issuer login session\n Proxy->>Proxy: Authenticate user and resolve CHG\n Proxy->>Proxy: Sign mint assertion with issuer private key\n Proxy->>Percents: POST widget session with assertion and chgId\n Percents->>JWKS: Fetch public key selected by kid (when needed)\n JWKS-->>Percents: JWKS public keys\n Percents->>Percents: Verify signature, issuer, audience, time, jti, and CHG ownership\n Percents-->>Proxy: Short-lived CHG-scoped widget token\n Proxy->>Proxy: Store widget token and create opaque proxy session\n Proxy-->>Browser: widgetUrl, proxyApiBaseUrl, opaque proxySessionToken\n Browser->>Iframe: Mount iframe and provide proxy session token\n Iframe->>Proxy: Widget request with opaque proxy session token\n Proxy->>Percents: Allowed widget request with server-side widget token\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant Browser as Issuer host app and browser\n participant Proxy as Issuer proxy\n participant Percents as Percents API\n participant JWKS as Issuer JWKS endpoint\n participant Iframe as Percents iframe\n\n Browser->>Proxy: Request widget proxy session using issuer login session\n Proxy->>Proxy: Authenticate user and resolve CHG\n Proxy->>Proxy: Sign mint assertion with issuer private key\n Proxy->>Percents: POST widget session with assertion and chgId\n Percents->>JWKS: Fetch public key selected by kid (when needed)\n JWKS-->>Percents: JWKS public keys\n Percents->>Percents: Verify signature, issuer, audience, time, jti, and CHG ownership\n Percents-->>Proxy: Short-lived CHG-scoped widget token\n Proxy->>Proxy: Store widget token and create opaque proxy session\n Proxy-->>Browser: widgetUrl, proxyApiBaseUrl, opaque proxySessionToken\n Browser->>Iframe: Mount iframe and provide proxy session token\n Iframe->>Proxy: Widget request with opaque proxy session token\n Proxy->>Percents: Allowed widget request with server-side widget token\n"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The issuer host app asks its own backend for a widget proxy session. Its existing issuer login session authenticates this request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The issuer proxy authenticates the user and resolves the user or business to a persisted Percents cardholder group (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]},"). Never accept a client-side-supplied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]}," as the source of truth."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The proxy creates a new signed mint assertion using its private key. The private key stays in issuer-controlled server-side infrastructure."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The proxy sends the assertion and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]}," to Percents to mint a widget session."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Percents selects the issuer's public key using the assertion's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kid"]},", retrieving the issuer's JWKS as needed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Percents validates the assertion's signature, algorithm, issuer, audience, expiry, issue time, unique ID, and ownership of the requested CHG."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Percents returns a short-lived widget token scoped to that CHG and widget-safe operations. The proxy stores this token server-side."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The proxy returns an opaque proxy-session token to the SDK. The browser and iframe use that token only with the issuer proxy; they never receive the signed assertion, private key, issuer API token, or Percents widget token."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mint-request","__idx":5},"children":["Mint Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The issuer proxy mints a Percents widget session with:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v2/widget/session\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"chgId\": \"chg_...\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[""]}," is an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc7515"},"children":["RS256 JSON Web Signature (JWS)"]}," carrying a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc7519"},"children":["JSON Web Token (JWT)"]},". It is sent only from the issuer proxy to Percents."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"assertion-fields","__idx":6},"children":["Assertion Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following fields are required for every signed mint assertion:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Location"},"children":["Location"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Why Percents validates it"},"children":["Why Percents validates it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Protected header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alg"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RS256"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ensures Percents uses the configured asymmetric signing algorithm and never accepts an unexpected algorithm."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Protected header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifier for a public key in the issuer's ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc7517"},"children":["JWKS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lets Percents select the correct public key and supports safe key rotation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iss"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer identifier supplied by Percents during onboarding"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifies the issuer making the assertion. Percents derives the issuer from this verified claim; do not send a separate issuer identifier in the request body."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Percents cardholder group being authorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Binds the assertion to one CHG. It must exactly match the request body and belong to the issuer identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iss"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aud"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Exact audience value supplied by Percents for this issuer and environment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifies the intended recipient: the Percents SDK-session endpoint. It prevents an assertion for another API or environment from being reused here."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iat"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time the assertion was issued"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allows Percents to reject assertions that are too old."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expiration time, no more than five minutes after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iat"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Limits the time in which a stolen assertion could be used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jti"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A new, unique assertion ID, such as a UUID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allows Percents to reject a replay of an assertion that has already been used."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"expected-audience","__idx":7},"children":["Expected Audience"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aud"]}," is the standard JWT ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["audience"]}," claim defined in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3"},"children":["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—not the issuer, the SDK, or the iframe."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc8725#section-3.9"},"children":["RFC 8725 section 3.9"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"production-onboarding-and-key-rotation","__idx":8},"children":["Production Onboarding and Key Rotation"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtain the issuer identifier and expected audience from your Percents account manager."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate and protect an RS256 private key in issuer-controlled server-side infrastructure. Do not expose it to a browser, mobile app, or client-side configuration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Publish the corresponding public key in a stable HTTPS JWKS endpoint, typically ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://issuer.example.com/.well-known/jwks.json"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide Percents with that JWKS URL. Percents uses it to verify assertions from the issuer proxy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When rotating keys, publish the new public key with a new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kid"]}," before the proxy begins signing with its corresponding private key. Keep the prior public key available until all assertions signed with it have expired."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Percents resolves the public key selected by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kid"]},", verifies the signature and claims, rejects a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jti"]}," that has already been used during the assertion's validity window, and confirms that the CHG belongs to the issuer identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iss"]},". Percents then returns a short-lived widget token restricted to that CHG and the widget-safe operations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["JWKS discovery supports signing-key rotation without sharing a secret or manually registering a new key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-requirements","__idx":9},"children":["Integration Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep issuer API tokens, signing keys, and widget tokens in server-side infrastructure only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use an expiring, opaque proxy session token in the browser; validate it on every proxy request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Allowlist only the widget routes the proxy needs. Do not turn the proxy into a general-purpose Percents API relay."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enforce the server-resolved CHG on every proxied request and remove ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]}," from browser-visible responses."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store proxy sessions and widget tokens in a shared, durable server-side store when using multiple proxy instances."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Restrict browser origins and iframe framing with appropriate CORS and CSP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["frame-ancestors"]}," configuration."]}]}]},"headings":[{"value":"SDK Authentication","id":"sdk-authentication","depth":1},{"value":"Trust Boundaries","id":"trust-boundaries","depth":2},{"value":"Session Flow","id":"session-flow","depth":2},{"value":"Production Mint Authentication","id":"production-mint-authentication","depth":2},{"value":"Authentication Flow","id":"authentication-flow","depth":3},{"value":"Mint Request","id":"mint-request","depth":3},{"value":"Assertion Fields","id":"assertion-fields","depth":3},{"value":"Expected Audience","id":"expected-audience","depth":3},{"value":"Production Onboarding and Key Rotation","id":"production-onboarding-and-key-rotation","depth":3},{"value":"Integration Requirements","id":"integration-requirements","depth":2}],"frontmatter":{"seo":{"title":"SDK Authentication"}},"lastModified":"2026-07-21T18:22:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/auth-security/sdk-auth","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}