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. 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.

The customer’s web application renders their 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 OAuth server (UX Toolkit API) — 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 OAuth server alongside the forwarded DPoP header in order to successfully request the access token.

The OAuth server 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 Marqeta’s OAuth endpoint.

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 Marqeta’s 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’s 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. 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
   })
   .setIssuedAt()
   .setIssuer('CLIENT_ID_HERE')
   .setSubject('CLIENT_ID_HERE')
   .setAudience('https://ux-toolkit-api.marqeta.com/')
   .setExpirationTime('1m')
   .setJti(uuid.v4())
   .sign(privateKeyPEM);
  console.log(jwt)
}

main();

Request your OAuth access token

Send a POST request to the /oauth/token endpoint 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. If you prefer to make the API call by executing a cURL command, use the sample below:

cURL

curl --location --request POST 'https://ux-toolkit-api.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.marqeta.com/'

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 Marqeta’s 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

​Authentication workflow

​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

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