Customer Authentication API

UX Toolkit requires you to build a Customer Authentication API on your backend that handles the OAuth 2.0 + DPoP token exchange with Marqeta and returns an access token to the UX Toolkit client.

Note
If you are on version 1 of the UX toolkit and would like to upgrade to version 2, you must migrate your UX Toolkit SDK to dedicated OAuth. Please see our How to migrate UX Toolkit to dedicated OAuth guide for instructions.

This page is the canonical reference for that API: the workflow, the implementation steps, and code samples.

Prerequisite
You must have completed the steps in Getting Started → Get access, including generating your RSA key pair and providing the public key to your Marqeta representative.

Authentication workflow

UX Toolkit uses a secure, Demonstrating Proof of Possession (DPoP)-based authentication methodology built on OAuth 2.0. OAuth 2.0 is the industry-standard authorization framework that lets your application securely access data without ever handling users’ credentials directly. Instead of sending a username and password on every request, your server exchanges tokens with an authorization server, minimizing risk and giving you fine-grained control over who can do what, and for how long. DPoP is a security mechanism within OAuth 2.0 that enhances token security by requiring the client to prove it possesses the private key used to obtain the token. This mechanism prevents unauthorized use of leaked or stolen tokens by binding the token to the client’s private key.

Your web application renders its page and initializes bootstrapping, passing the URL to the Customer Authentication API as a parameter.

The UX Toolkit SDK generates a public/private key pair. The private key is used to sign the DPoP proof header, while the public key will be used later by the Identity Provider (IdP) or UX Toolkit API for validation.

The client sends the DPoP header to the Customer Authentication API, which forwards it as-is to the dedicated OAuth host — the Customer Authentication API does not generate or modify the DPoP header. The DPoP header is a short-lived JSON Web Token (JWT) that includes the public key and is signed by the private key. The Customer Authentication API’s responsibility at this step is to generate a client assertion token and send it to the dedicated OAuth host alongside the forwarded DPoP header in order to successfully request the access token.

The dedicated OAuth host issues a DPoP-bound OAuth token, embedding the thumbprint of the client’s public key as a property of the OAuth JWT. This binding ties the token to the client’s key pair — a compromised OAuth token alone cannot be used to call the API, since possession of the corresponding DPoP private key is also required.

For each subsequent request to the UX Toolkit API, the client generates a new, unique DPoP proof JWT (signed by the private key) and includes it in the request. The UX Toolkit API validates the DPoP header on every request, matching the public key in the header with the thumbprint in the OAuth token to confirm that the sender possesses the private key and is the owner of the OAuth token.

Note
UX Toolkit components automatically request a new access token from the Customer Authentication API when the access token nears expiration (within 60 seconds of expiry) or has already expired. Access tokens expire every 60 minutes, and the SDK refreshes them as many times as necessary for the duration of the user’s session — there is no cap on the number of refresh requests. Each refresh request hits your Customer Authentication API, which is responsible for validating that the request is authenticated according to your own security requirements before forwarding it to the Marqeta OAuth endpoint.

Endpoints

Your Customer Authentication API works with two different Marqeta URLs, and they are not interchangeable:

The dedicated OAuth host: Where you send the token request. You also use it for the aud claim of your client assertion.
The audience parameter: The UX Toolkit API that the returned access token grants access to. This is a value you send in the request body, not a host you call.

Environment	Dedicated OAuth host	audience
Sandbox	`https://secure-sandbox.marqeta.com`	`https://ux-toolkit-api-sandbox.marqeta.com`
Production	`https://secure.marqeta.com`	`https://ux-toolkit-api.marqeta.com`

Use the sandbox values in both columns while you develop, then switch both to the production values when you are ready to go live. Mixing environments, such as pairing a sandbox OAuth host with a production audience, causes the request to fail.

Note
If you are on version 1 of UX Toolkit, your integration mints tokens at the UX Toolkit API host rather than at the dedicated OAuth host shown above. It continues to work, and you can migrate at your own pace. To learn how, see How to migrate UX Toolkit to dedicated OAuth.

Authentication steps

In order to authenticate UX Toolkit via OAuth, you need to complete the following steps:

Configure CORS on your API endpoint

Create your client assertion token

Request your OAuth access token

Return your OAuth access token

Note
For an example of the expected shape of the Customer Authentication API, download the example OpenAPI definition

Configure CORS on your API endpoint

Your Customer Authentication API server must allow cross-origin requests from the Marqeta UX Toolkit web domain. Include the Access-Control-Allow-Origin property in your HTTP response header, as shown below.

JavaScript

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', 'https://web.ux-toolkit.marqeta.com');
  next();
});

Including the HTTP response header ensures that requests originating from the Marqeta web client will not be blocked by Cross-Origin Resource Sharing (CORS) policies. Without this header, requests from https://web.ux-toolkit.marqeta.com will fail due to CORS restrictions, and Marqeta will not be able to successfully interact with your OAuth endpoint.

Note
You only need this CORS header if you plan to use Marqeta iframe content as mobile webviews.

Create your client assertion token

The client assertion token must be signed with the private key that you generated in the Create RSA Keys section. Marqeta recommends that you construct the token using standard tooling or third-party libraries that support JWT signing out of the box, rather than implementing them from scratch yourself. To learn more about supporting libraries, visit JWT.io. In the header, set alg to the signing algorithm and kid to the key ID that your Marqeta representative provided alongside your client ID. The kid identifies which of your registered public keys the dedicated OAuth host verifies the signature against. Set the claims of the assertion as follows:

Claim	Value
iss	Your OAuth client ID, provided by your Marqeta representative.
sub	Your OAuth client ID, provided by your Marqeta representative.
aud	The full token endpoint URL, including the `/oauth/token` path. In sandbox, this is `https://secure-sandbox.marqeta.com/oauth/token`.
exp	An expiration no more than five minutes after the time the assertion was issued.
jti	A unique identifier for the assertion.

Important
The aud claim must be the full token endpoint URL, including the /oauth/token path — not the OAuth host on its own. An assertion that sets aud to the bare host, or that expires more than five minutes after it was issued, is rejected with a 401 invalid_client response.

The example below uses the sandbox values. Once you are ready to switch to a production environment, you must replace them with the production values from the Endpoints table and re-create your client assertion token. If the URLs in your token exchange do not match the environment you are targeting, the request fails.

The Node.js script below uses a jose package to generate the assertion:

JavaScript

const { SignJWT } = require('jose')
const crypto = require("crypto");
const uuid = require("uuid");

async function main() {
 const privateKeyPEM = crypto.createPrivateKey(/**
   Read the content of your private key here. We recommend storing your private key
   in a secure infrastructure.
 */);

 const jwt = await new SignJWT({})
   .setProtectedHeader({
      alg: 'RS256', // or RS384 or PS256
      kid: 'KEY_ID_HERE', // The key ID Marqeta provided alongside your client ID
   })
   .setIssuedAt()
   .setIssuer('CLIENT_ID_HERE')
   .setSubject('CLIENT_ID_HERE')
   .setAudience('https://secure-sandbox.marqeta.com/oauth/token') // The full token endpoint URL, including the path
   .setExpirationTime('1m') // Five minutes maximum
   .setJti(uuid.v4())
   .sign(privateKeyPEM);
  console.log(jwt)
}

main();

Request your OAuth access token

Send a POST request to the /oauth/token endpoint of the dedicated OAuth host with your client credentials, including the DPoP proof JWT in a DPoP header. This endpoint generates your UX Toolkit OAuth access token, which enables access to the specified account and is returned to the UX Toolkit client. Forward the DPoP header exactly as your UX Toolkit client sent it. Your Customer Authentication API neither generates nor modifies the DPoP proof. If you prefer to make the API call by executing a cURL command, use the sample below:

Important
If you set up a sandbox environment while working through the getting started section, you must use the sandbox values everywhere in your token exchange. The example below uses the sandbox values. Once you are done configuring and working inside of your Sandbox environment, you will need to replace them with the production values from the Endpoints table. If the URLs in your token exchange do not match the environment you are targeting, the request fails.

cURL

curl --location --request POST 'https://secure-sandbox.marqeta.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header "DPoP: $DPOP_PROOF" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode "client_assertion=$CLIENT_ASSERTION" \
  --data-urlencode 'user_token=some-user-token' \
  --data-urlencode 'audience=https://ux-toolkit-api-sandbox.marqeta.com'

The audience parameter stays set to the UX Toolkit API even though you send the request to the dedicated OAuth host. It identifies the API that the returned access token grants access to. For full details on the POST /oauth/token endpoint, see Generate UX Toolkit OAuth access token in the UX Toolkit API reference.

Return your OAuth access token

After your Customer Authentication API has successfully generated the client assertion and exchanged it with the OAuth endpoint for an access token, send the resulting access token back to the UX Toolkit client as the response to the bootstrap() request. The UX Toolkit client will use this token for subsequent component requests, automatically refreshing it when it nears expiration. Because access tokens expire every 60 minutes, the SDK will call your Customer Authentication API approximately every 60 minutes for as long as the user’s session is active. There is no limit to the number of times the SDK will request a new token. Your Customer Authentication API must validate every incoming refresh request — for example, by verifying the user’s session or applying your own authentication and authorization checks — before exchanging credentials with the Marqeta OAuth endpoint.

Wiring it up on the client

Once your Customer Authentication API is live, you’ll need to point the UX Toolkit client at it via the bootstrap() function. The apiEndpoint field of authParams is what connects the client to this API. For the full list of bootstrap() properties and code examples, see the Bootstrap properties section of the Customizing UX Toolkit page.

Getting Started - install UX Toolkit and ship a Quick Start example
Bootstrap properties - full client-side bootstrap() reference
Working within Native Webviews - additional auth requirements for embedding in mobile webviews
Example OpenAPI definition - reference shape for the Customer Authentication API
How to migrate the UX Toolkit to dedicated OAuth - OAuth migration steps required to upgrade from version 1 to version 2 of UK toolkit

​Authentication workflow

​Endpoints

​Authentication steps

​Configure CORS on your API endpoint

​Create your client assertion token

​Request your OAuth access token

​Return your OAuth access token

​Wiring it up on the client

​Related

Authentication workflow

Endpoints

Authentication steps

Configure CORS on your API endpoint

Create your client assertion token

Request your OAuth access token

Return your OAuth access token

Wiring it up on the client

Related