UX Toolkit

The UX Toolkit endpoints form the link between the Marqeta platform and your code. They enable you to obtain the access you need to upload the themes you develop using the Studio interactive design environment and apply them to the card products in your card program. This is also how you can upload the card art associated with a theme for display in Studio and in your application as part of various UI components. Before using the API endpoints, follow the UX Toolkit Getting Started guide to learn how to properly install and begin working with UX Toolkit.

Important
This version of UX Toolkit supports prepaid and debit card programs in the United States, Canada, and the EU.

Base URLs

There are two dedicated URLs for working with UX Toolkit: a sandbox URL and a base URL.

HTML

https://ux-toolkit-api.marqeta.com
https://ux-toolkit-api-sandbox.marqeta.com

Use the sandbox URL for developing your card product. Use the base URL to build your endpoints for a production environment. For an overview of the UX Toolkit platform, see About UX Toolkit. For information on the available UX Toolkit web components, see Working with UX Toolkit Web Components.

Generate UX Toolkit OAuth access token

Action: POST
Endpoint: /oauth/token Use this endpoint to generate your UX Toolkit OAuth access token. For details, see UX Toolkit Getting Started.

Request header

Fields	Description
DPoP string Required	A valid Demonstrating Proof of Possession (DPoP) JSON Web Token (JWT). Allowable Values: Valid DPoP proof JWT

Request body

Fields	Description
grant_type string Required	Type of OAuth 2.0 grant. Must be set to `client_credentials`. Allowable Values: `client_credentials`
client_assertion_type string Required	Indicates the type of JWT-based client assertion for authentication. Must be set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. Allowable Values: `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
client_assertion string Required	Signed JWT that asserts the client’s identity. For more information, see Create your client assertion token. Allowable Values: Valid client assertion
user_token string Required	Unique identifier of the user account holder. Allowable Values: Existing user token 1-36 chars
audience string Required	Intended audience of the returned access token. This value should match the base URL of the UX Toolkit API. Allowable Values: `<a href="https://ux-toolkit-api-sandbox.marqeta.com">https://ux-toolkit-api-sandbox.marqeta.com</a>`, `<a href="https://ux-toolkit-api.marqeta.com">https://ux-toolkit-api.marqeta.com</a>`

Sample request body

JSON

{
  "audience": "https://ux-toolkit-api-sandbox.marqeta.com",
  "grant_type": "client_credentials",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkZmcxZGFmYS00NTY3LTY3ODktMTI0NS1nNTQ1N3NkZmhqaGYiLCJzdWIiOiJkZmcxZGFmYS00NTY3LTY3ODktMTI0NS1nNTQ1N3NkZmhqaGYiLCJhdWQiOiJodHRwczovL3V4LXRvb2xraXQtYXBpLXNhbmRib3gubWFycWV0YS5jb20iLCJpYXQiOjE3NDg4ODM3MjUsImV4cCI6MTc0ODg4NDAyMywianRpIjoiYXMxMmRqZmEtMzQ1Ni0xMzQxLTM0NTYtYTM0NTdzZHNkZnNhIn0.ciKc74t2MqFuXJuTJS54ovupuuXMCbsU2Lk9BQzfA_A",
  "user_token": "a94c2e7e-9383-4486-9759-8c04cf672e4e"
}

Response body

Fields	Description
access_token string Returned	DPoP-bound JWT that must be passed back to UX Toolkit client via your Customer Authentication API. Allowable Values: Valid access token
expires_in number Returned	Number of seconds for which the returned `access_token` will remain valid. Allowable Values: Any integer
token_type string Returned	Identifies the token type. For DPoP flows, this value is always `DPoP`. Allowable Values: `DPoP`

Sample response body

JSON

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwieCI6ImdIM3F5X0xRS3Q3NW9Bejg0R0hhRW5IVUdaVzIydjdFdkhPcmEtSUZqTTAiLCJ5IjoieFlDcDVIUjVHbV90UVBQQ0ZyLU1TUUd1TEYtRkhtbWlEaEl4U3g4MUh6TSIsImNydiI6IlAtMjU2In19.eyJhdGgiOiJ6VVdYc3hicmt6MGtlM0pHQm93UzZRYXVCaVZjWDhPeVY2T3lGQURDT05nIiwiaHR1IjoiaHR0cHM6Ly91eC10b29sa2l0LWFwaS1zYW5kYm94Lm1hcnFldGEuY29tL2FwaS92MS9hdXRoL3Byb2dyYW0tc2hvcnQtY29kZSIsImh0bSI6IkdFVCIsImp0aSI6IjgxNjc2YWQxLTM0MmMtNDZhNi05OTg5LWFiMWFlOWZhZGMxMCIsImlhdCI6MTc0ODkwNTczMSwiZXhwIjoxNzQ4OTA1NzkxfQ.fP3s2El6PlBfJUI-Pc98T6GdPTZgKvFmFnWx75QtOdhTXNJz9RVNEcddIK7YHpbubETcrvs6LZm-vAwZ1B7R1g",
  "token_type": "DPoP",
  "expires_in": 3600
}

Generate UX Toolkit authentication token

Action: POST
Endpoint: /auth/login

Warning
This endpoint has been deprecated. Refer to the Authentication workflow section of UX Toolkit Getting Started for details on how to authenticate with OAuth 2.0.

Use this endpoint to generate your UX Toolkit authentication token. This token enables access to the specified account in order for your application’s back end to pass it to your JavaScript. For details, see UX Toolkit Getting Started.

Request body

Fields	Description
user_token string Required	Unique identifier of the user account holder. Allowable Values: 1–36 chars Existing user token

Sample request body

JSON

{
  "user_token": "a94c2e7e-9383-4486-9759-8c04cf672e4e"
}

Response body

Fields	Description
program_short_code string Returned	Program short code on the Marqeta platform. Allowable Values: Existing program short code
token string Returned	Token string to be passed to the UX Toolkit’s `bootstrap()` method. Allowable Values: Authentication token

Sample response body

JSON

{
  "program_short_code": "myprgrm",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9ncmFtX3Nob3J0X2NvZGUiOiJteXByZ3JtIiwidXNlcl90b2tlbiI6IjE0OWNjYjVmLWUwZDYtNGMwZS05MjAzLWJkMDkyZGI0N2UzNCJ9.6TdyvMOa_eUSvN5GpUZKBOgcHxmWTuYQPMEgNwBfVS0"
}

Upload theme object

Action: POST
Endpoint: /theme Use this endpoint to upload your theme as a JSON object. Once you have finalized your application’s theme using the Studio environment, you can upload it to Marqeta for use with your card product. For details, see UX Toolkit Getting Started.

Request body

Fields	Description
theme object Optional	Collection of the configurable values that have been defined to create a customized look-and-feel for a card product. NOTE: Each card product in your card program can have its own theme. Allowable Values: JSON object
theme_name string Optional	Descriptive name used to identify this theme. NOTE: The theme name you choose must be unique across your card program. If you do not supply a value, the theme will be named `default`. Allowable Values: 1–32 chars

Sample request body

JSON

{
    "theme_name": "the-best-card-product",
    "theme": "**Your_JSON_Theme_Object**"
}

Sample response body

There is no response for a call made to the POST /theme endpoint, other than a 201 Successfully uploaded a theme message.

JSON

HTTP response code 201

For the full list of codes supported by the Marqeta platform, see HTTP response codes.

Upload card art

Action: POST
Endpoint: /cardproducts/cardart Use this endpoint to upload card art for a specific program. Send the request as a multi-part form data request. Your card art images are displayed in the Studio environment and in your application. For details, see UX Toolkit Getting Started.

Request body

Fields	Description
card_product_token string Required	Unique identifier of the card product. Allowable Values: 1–36 chars Existing card product token.
program_short_code string Returned	Program short code on the Marqeta platform. Allowable Values: Existing program short code
asset_type string Required	Type of card asset. Allowable Values: `front`, `back`, `thumbnail`
file string Required	Specifies a card art image in PNG format. Allowable Values: Portable network graphics file (`*.PNG`)

Sample request body

MIME

POST /api/v1/cardproducts/cardart HTTP/1.1
Host: https://ux-toolkit-api.marqeta.com
Authorization: Basic <Authorization token here>
Content-Type: multipart/form-data; boundary=----<Boundary here>

------<Boundary here>
Content-Disposition: form-data; name="card_product_token"

754f7c13-c347-4fc9-80d7-b4c4fc36062d
------<Boundary here>
Content-Disposition: form-data; name="program_short_code"

program
------<Boundary here>
Content-Disposition: form-data; name="asset_type"

back
------<Boundary here>
Content-Disposition: form-data; name="file"; filename="card-back.png"
Content-Type: image/png

(data)
------<Boundary here>--

Sample response body

There is no response for a call made to the POST /cardproducts/cardart endpoint, other than a 201 Successfully uploaded card art message.

JSON

HTTP response code 201

For the full list of codes supported by the Marqeta platform, see HTTP response codes.

Upload custom translation files

Action: POST
Endpoint: /translations

ImportantBefore uploading your translation files using the /translations endpoint, ensure that they are linguistically accurate and representative of the user experience.

Use this endpoint to upload custom translation files for a specific program. This endpoint allows you to customize the values for the keys contained in the translations object so that they will appear in the target language in the customer-facing UI. UX Toolkit uses key and value pairs to render the translations used in web components. Each key is an identifier used to reference a specific piece of content in a web component, while the value is the translated text string that replaces that key on the customer-facing UI. See the sample request body that follows for an example. For a full list of keys, contact your Marqeta onboarding specialist. See also the Using custom translation files section in the UX Toolkit Getting Started guide.

Request body

Fields	Description
program_short_code string Required	Program short code on the Marqeta platform. Allowable Values: Existing program short code
language_code string Required	Language code associated to translations. Allowable Values: `bg-BG`, `ca-ES`, `cs-CZ`, `de-DE`, `el-GR`, `en-GB`, `en-US`, `es-ES`, `et-EE`, `fr-CA`, `fr-FR`, `hr-HR`, `hu-HU`, `it-IT`, `lt-LT`, `nl-NL`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sl-SI`, `sv-SE`
translations object Required	Object that contains a list of key/value pairs for translations. For a full list of keys, contact your Marqeta onboarding specialist. Allowable Values: Valid JSON object

Sample request body

JSON

{
  "program_short_code": "mqtest",
  "language_code": "es-ES",
  "translations": {
      "translation": {
          "activate_card": "Activar tu tarjeta",
          "replace_card": "Reemplazar tu tarjeta"
      }
  }
}

Sample response body

The only response for a call made to the /translations endpoint is 201 Successfully uploaded a translation.

JSON

HTTP response code 201

For the full list of codes supported by the Marqeta platform, see HTTP response codes

​Base URLs

​Generate UX Toolkit OAuth access token

​Request header

​Request body

​Sample request body

​Response body

​Sample response body

​Generate UX Toolkit authentication token

​Request body

​Sample request body

​Response body

​Sample response body

​Upload theme object

​Request body

​Sample request body

​Sample response body

​Upload card art

​Request body

​Sample request body

​Sample response body

​Upload custom translation files

​Request body

​Sample request body

​Sample response body

Base URLs

Generate UX Toolkit OAuth access token

Request header

Request body

Sample request body

Response body

Sample response body

Generate UX Toolkit authentication token

Request body

Sample request body

Response body

Sample response body

Upload theme object

Request body

Sample request body

Sample response body

Upload card art

Request body

Sample request body

Sample response body

Upload custom translation files

Request body

Sample request body

Sample response body