Customizing UX Toolkit

Once you have a working integration, this page is your reference for customizing UX Toolkit’s appearance and behavior — bootstrap configuration, themes, card art, and translations.

Bootstrap properties

The window.marqeta.bootstrap() function is the single entry point for configuring UX Toolkit at runtime. The fields below are passed to it.

Field	Description
`authParams.apiEndpoint`	Required. Fully-qualified URL of your Customer Authentication API endpoint.
`authParams.apiHeadersResolver`	Optional. A `HeadersInit` object — or a sync/async method returning one — used to pass session or auth token headers to your authentication API.
`envName`	Optional. Environment being targeted. Allowable values: `sandbox` or `production`. Default: `production`.
`themeName`	Optional. The name of an existing theme created via the `/theme` endpoint. Default: `default`. See Themes.
`languageCode`	Optional. The language code for custom translation files uploaded via the `/translations` endpoint. Default: `en-US`. See Translations.

Bootstrap examples

Minimal — sandbox, default theme, default language:

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
  },
  envName: "sandbox",
});

Full — custom theme, custom language, with auth headers:

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
    apiHeadersResolver: {
      "Authentication": "Bearer your-website-session-token-here"
    },
  },
  envName: "sandbox",
  themeName: "new-theme-name",
  languageCode: "es-ES"
});

Async headers resolver (e.g., when your auth header changes per request):

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
    apiHeadersResolver: async () => {
      const token = await getCurrentSessionToken();
      return { "Authentication": `Bearer ${token}` };
    },
  },
  envName: "production",
});

Themes

UX Toolkit components ship with a default theme; you can customize this theme so the components align more closely with your brand. Theming is a two-part workflow:

Design your theme in Studio — an interactive design environment.
Upload your theme via the API — the POST /theme endpoint deploys it to the Marqeta platform for use with your card program.

Designing your theme in Studio

Studio is an interactive theming environment where you can fine-tune the appearance of UX Toolkit UI components before integrating them. With Studio, you can preview and test the look-and-feel of components on various device types (mobile phone, tablet, and desktop). While in Studio, you can click into each component to access its full functionality. Each component has both an Overview page and a Customize page that are linked together — any changes made on the Customize page carry over to the Overview page. You can choose to work in Studio with or without authenticating:

Authenticated mode — Studio is populated with your program’s details and data instead of using the default Studio-simulated data.
Unauthenticated mode — you work with the simulated data Studio provides.

Important
To work in Studio while authenticated, contact your Marqeta representative to obtain the Auth Params CLI script for your Auth Params. To run the Auth Params CLI script, you will need Node.js v16 (or later) installed and the items below.

Name	Description	How to obtain
Client ID	Your OAuth client identifier.	Contact your Marqeta representative.
Private PEM file name	Your private PEM file. This file should live in the same directory as the Auth Params CLI script. Do not share this PEM file externally.	The file name is created when generating your RSA key pair. See Create RSA keys on the Getting Started page..
User token	Unique identifier of the user account holder. Allowable values: 36 char max.	Send a `POST /users` request to generate a user token.
OAuth URL	The OAuth URL used for the client assertion.	Sandbox: `https://ux-toolkit-api-sandbox.marqeta.com` · Production: `https://ux-toolkit-api.marqeta.com`

Run the Auth Params CLI script, replacing each placeholder with your value from the table above:

node path/to/generateAuthParams.js \
  <client-id> \
  <private-pem-file-name> \
  <user-token> \
  <oauth-url>

For example, to generate auth params for the sandbox environment:

node path/to/generateAuthParams.js \
  example-client-id \
  private_key.pem \
  09d921f5-d6be-4d2d-aaa2-d2a796f93232 \
  https://ux-toolkit-api-sandbox.marqeta.com

When the script runs successfully, it prints an auth params JSON object to the terminal. Copy the full JSON object — you will paste it into Studio when authenticating. Example output:

{
  "keyPair": {
    "publicJwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "<base64url>",
      "y": "<base64url>",
      "alg": "ES256"
    },
    "privateJwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "<base64url>",
      "y": "<base64url>",
      "alg": "ES256",
      "d": "<base64url>"
    }
  },
  "token": "<access_token>",
  "expiresAt": 1234567890000
}

Authenticate when working with Studio

To authenticate when working with Studio, follow these steps:

Access Studio.
In the upper-left corner of the screen, click the Authentication icon to load the modal window.
Select the Authenticate option button.
Paste the JSON output from the script into the Auth Params field, then click Authenticate. When the icon turns green, you have successfully switched to authenticated mode.

If you are part of a collaborative effort building a theme and want to share your work with others, share the theme as a JSON file. Consider hosting a copy of your theme’s JSON file in your source control repository for safekeeping so you can monitor incremental changes made to it by team members. Your Studio theme is not applied to your card product or program until you upload it to the Marqeta platform via the POST /theme endpoint (see Uploading your theme via the API, below). You cannot download and edit a Studio theme once it has been uploaded to the Marqeta platform. The Marqeta platform does not retain a version history of your theme’s JSON file. To edit a locally saved copy of your theme:

Paste your theme’s JSON content into Studio.
Make your modifications directly in the Studio interface.
Save the JSON file locally or in your source control repository.
Upload the JSON file to the Marqeta platform to overwrite the existing theme.

UX Toolkit does not limit you to a single theme per card program. You can define multiple themes and apply a different theme to each card product, for example. The only constraint is that all themes for a given card program must have unique names.

Note
If you close or refresh the browser tab where Studio is running, your customized theme values will be lost. Likewise, if you authenticate with Studio, you will be logged out after closing or refreshing the Studio tab.

Uploading your theme via the API

After you have developed your theme in Studio, save it as a JSON file and upload a copy to the Marqeta platform. The example cURL below uploads a theme named new-theme-name:

curl --location 'https://ux-toolkit-api.marqeta.com/api/v1/theme' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {{BASE64_APPLICATION_AND_ADMIN_ACCESS_TOKENS}}' \
  --data '{
    "theme_name": "new-theme-name",
    "theme": {{THEME_JSON_HERE}}
  }'

Then update the call you make to bootstrap() to include the theme:

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
  },
  envName: "sandbox",
  themeName: "new-theme-name",
});

For full reference of the POST /theme endpoint, see Uploading a Studio theme in the UX Toolkit API reference.

Card art

UX Toolkit lets you upload custom card art for each card product in your program. You can submit up to three images per card product:

An image displayed on the front of the card.
An image displayed on the back of the card (digital cards only — virtual cards have no back image).
A thumbnail-sized image of the front of the card.

If you do not upload card art, default images are displayed by UX Toolkit. Card art is shown in Studio and in your application as part of the mq-card and mq-card-list components.

Important
The card art you select must be preapproved by Marqeta, your bank, and the card network. It should adhere to card-network guidelines and may include details that are part of the bank approval process, such as the issuing bank name. Contact your Marqeta representative for details.

Digital (physical) cards

Front of card. A digital version of the front of the physical card

Back of card. A digital version of the back of the physical card.

Thumbnail. An optional scaled-down version of the front-of-card image. If you don’t submit a thumbnail, default imagery from the card network will be displayed instead.

Virtual cards

Front of card. Represents the virtual card. Virtual cards have no back-of-card image.

Thumbnail. An optional scaled-down version of the virtual card image.

Card art specifications

Submitted images must adhere to the following specifications:

Property	Requirement
File format	PNG (`*.png`)
Image orientation	Landscape only
File size on disk	Maximum 5 MB per image. Avoid using a large file that must be resized for display.
Image size on screen	Front/back: 1536 × 969 px (proportional to ISO ID-1 card size). Thumbnail: 60 × 36 px.
Corner radius	0.1233” (3.13182 mm)
Resolution	72 PPI
Color model	RGB
Color depth	16+ bit, non-interlaced

Uploading card art to the Marqeta platform

After your images have been approved by Marqeta, your bank, and the card network, you can upload them to the Marqeta platform for use in Studio and your application. You can upload card art via the /cardproducts/cardart endpoint of the UX Toolkit service. The example cURL below uploads file.png:

curl -X POST "https://ux-toolkit-api.marqeta.com/api/v1/cardproducts/cardart" \
  -H "Authorization: Basic $(echo -n '{{APPLICATION_TOKEN}}:{{ACCESS_TOKEN}}' | base64)" \
  -F "program_short_code={{program_short_code}}" \
  -F "card_product_token={{card_product_token}}" \
  -F "asset_type={{asset_type}}" \
  -F "file=@/path/to/your/file.png"

Valid asset_type values: front, back, thumbnail. For full reference, see Upload card art in the UX Toolkit API reference.

Translations

UX Toolkit web components default to American English (en-US). The internationalization feature lets you change the language of components by uploading custom translation files via the /translations endpoint and referencing them in bootstrap().

Important
Before uploading translation files, ensure that they are linguistically accurate and representative of the user experience.

Working with custom translation files

Note
Upload your custom translation files via the /translations endpoint before calling the bootstrap() function — bootstrap() references them by language code, so they must already exist on the Marqeta platform when the call is made.

To include custom translation files when bootstrapping UX Toolkit:

Ensure your custom translation files are linguistically accurate.
Upload them via the /translations endpoint. (See Upload custom translation files in the UX Toolkit API reference.)
Important
The /translations endpoint requires the request body to include program_short_code, language_code, and translations. Missing any of these returns a 400 Bad Request error.
Test your files in Studio.
Update your bootstrap() call to include the language code:

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
  },
  envName: "sandbox",
  themeName: "new-theme-name",
  languageCode: "es-ES"
});

For the full list of keys you can use in your custom translation files, contact your Marqeta onboarding specialist.

Testing translations in Studio

You can use Studio to test translation values.

Note
To test custom translation files, you must be authenticated within Studio.

Request the translations object file for your target language from Marqeta.
Customize the values in the object file in your target language.
Send a request using the customized object to the /translations endpoint.
Authenticate in Studio. To switch to authenticated mode, follow these steps:
1. Access Studio.
2. In the upper-left corner of the screen, click the Authentication icon to load the modal window.
3. Select the Authenticate option button.
4. Paste the JSON output from the script into the Auth Params field, then click Authenticate. When the icon turns green, you have successfully switched to authenticated mode.
In Studio, click the globe icon in the top menu navigation bar to confirm your custom translations have been applied. Available languages are listed in the drop-down beneath the globe icon.
Select a language from the list.

Note
Use the Customize tab in Studio to view any updates that you have made to the components’ display language.

​Bootstrap properties

​Bootstrap examples

​Themes

​Designing your theme in Studio

​Authenticate when working with Studio

​Editing and sharing an existing Studio theme

​Uploading your theme via the API

​Card art

​Digital (physical) cards

​Virtual cards

​Card art specifications

​Uploading card art to the Marqeta platform

​Translations

​Working with custom translation files

​Testing translations in Studio

Bootstrap properties

Bootstrap examples

Themes

Designing your theme in Studio

Authenticate when working with Studio

Editing and sharing an existing Studio theme

Uploading your theme via the API

Card art

Digital (physical) cards

Virtual cards

Card art specifications

Uploading card art to the Marqeta platform

Translations

Working with custom translation files

Testing translations in Studio