> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UX Toolkit

> See the reference documentation for the APIs that are part of the UX Toolkit experience.

export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
      text: "mint-text-green-700 dark:mint-text-green-400",
      border: "mint-border-green-300 dark:mint-border-green-700"
    },
    POST: {
      bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
      text: "mint-text-blue-700 dark:mint-text-blue-400"
    },
    PUT: {
      bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
      text: "mint-text-yellow-700 dark:mint-text-yellow-400"
    },
    PATCH: {
      bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
      text: "mint-text-orange-700 dark:mint-text-orange-400"
    },
    DELETE: {
      bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
      text: "mint-text-red-700 dark:mint-text-red-400"
    },
    API: {
      bg: "mint-bg-black",
      text: "mint-text-white"
    }
  };
  const MethodBadge = ({method}) => {
    const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
    return <span className={`
          method-pill rounded-lg font-semibold px-1.5 py-0.5 text-xs leading-5 ${style.bg} ${style.text}`}>
        {method?.toUpperCase()}
      </span>;
  };
  const content = <div className="group flex items-center gap-4 border border-gray-200 dark:border-gray-700 rounded-xl p-5 hover:border-gray-400 dark:hover:border-gray-500 hover:shadow-md transition-all cursor-pointer">
      {}
      <div className="shrink-0">
        <MethodBadge method={method} />
      </div>
      {}
      <div className="flex-1 min-w-0">
        <p className="font-semibold text-gray-900 dark:text-white text-sm leading-snug">{title}</p>
        {children && <p className="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">{children}</p>}
      </div>
    </div>;
  if (!href) return content;
  return <a href={href} className="block no-underline border-b-0 mb-2">
      {content}
    </a>;
};

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](/developer-guides/about-ux-toolkit/#_studio_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](/developer-guides/uxt-getting-started/) guide to learn how to properly install and begin working with UX Toolkit.

<Warning>
  **Important**\
  This version of UX Toolkit supports prepaid and debit card programs in the United States, Canada, and the EU.
</Warning>

<h2 id="_base_urls">
  Base URLs
</h2>

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

```html HTML lines wrap theme={null}
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](/developer-guides/about-ux-toolkit/). For information on the available UX Toolkit web components, see [Working with UX Toolkit Web Components](/developer-guides/uxt-web-components/).

<h2 id="_generate_ux_toolkit_oauth_access_token">
  Generate UX Toolkit OAuth access token
</h2>

**Action:** `POST`\
**Endpoint:** `/oauth/token`

{/* <EndpointCard
title="Generate UX Toolkit OAuth access token"
path="/oauth/token"
method="post"
/> */}

Use this endpoint to generate your UX Toolkit OAuth access token. For details, see [UX Toolkit Getting Started](/developer-guides/uxt-getting-started/).

<h3 id="_request_header">
  Request header
</h3>

| Fields                                     | Description                                                                                                                             |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| DPoP<br /><br />string<br /><br />Required | A valid Demonstrating Proof of Possession (DPoP) JSON Web Token (JWT).<br /><br />**Allowable Values:**<br /><br />Valid DPoP proof JWT |

<h3 id="_request_body">
  Request body
</h3>

| Fields                                                        | Description                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| grant\_type<br /><br />string<br /><br />Required             | Type of OAuth 2.0 grant. Must be set to `client_credentials`.<br /><br />**Allowable Values:**<br /><br />`client_credentials`                                                                                                                                                                                                                       |
| client\_assertion\_type<br /><br />string<br /><br />Required | Indicates the type of JWT-based client assertion for authentication. Must be set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.<br /><br />**Allowable Values:**<br /><br />`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`                                                                                                   |
| client\_assertion<br /><br />string<br /><br />Required       | Signed JWT that asserts the client’s identity. For more information, see <a href="/developer-guides/uxt-getting-started/#_create_your_client_assertion_token">Create your client assertion token</a>.<br /><br />**Allowable Values:**<br /><br />Valid client assertion                                                                             |
| user\_token<br /><br />string<br /><br />Required             | Unique identifier of the user account holder.<br /><br />**Allowable Values:**<br /><br />Existing user token<br /><br />1-36 chars                                                                                                                                                                                                                  |
| audience<br /><br />string<br /><br />Required                | Intended audience of the returned access token. This value should match the base URL of the UX Toolkit API.<br /><br />**Allowable Values:**<br /><br />`<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>` |

<h3 id="_sample_request_body">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "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"
}
```

<h3 id="_response_body">
  Response body
</h3>

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

<h3 id="_sample_response_body">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwieCI6ImdIM3F5X0xRS3Q3NW9Bejg0R0hhRW5IVUdaVzIydjdFdkhPcmEtSUZqTTAiLCJ5IjoieFlDcDVIUjVHbV90UVBQQ0ZyLU1TUUd1TEYtRkhtbWlEaEl4U3g4MUh6TSIsImNydiI6IlAtMjU2In19.eyJhdGgiOiJ6VVdYc3hicmt6MGtlM0pHQm93UzZRYXVCaVZjWDhPeVY2T3lGQURDT05nIiwiaHR1IjoiaHR0cHM6Ly91eC10b29sa2l0LWFwaS1zYW5kYm94Lm1hcnFldGEuY29tL2FwaS92MS9hdXRoL3Byb2dyYW0tc2hvcnQtY29kZSIsImh0bSI6IkdFVCIsImp0aSI6IjgxNjc2YWQxLTM0MmMtNDZhNi05OTg5LWFiMWFlOWZhZGMxMCIsImlhdCI6MTc0ODkwNTczMSwiZXhwIjoxNzQ4OTA1NzkxfQ.fP3s2El6PlBfJUI-Pc98T6GdPTZgKvFmFnWx75QtOdhTXNJz9RVNEcddIK7YHpbubETcrvs6LZm-vAwZ1B7R1g",
  "token_type": "DPoP",
  "expires_in": 3600
}
```

<h2 id="generate_auth_token">
  Generate UX Toolkit authentication token
</h2>

**Action:** `POST`\
**Endpoint:** `/auth/login`

{/* <EndpointCard
title="Generate UX Toolkit authentication token"
path="/auth/login"
method="post"
/> */}

<Danger>
  **Warning**\
  This endpoint has been deprecated. Refer to the [Authentication workflow](/developer-guides/uxt-getting-started/#_authentication_workflow) section of [UX Toolkit Getting Started](/developer-guides/uxt-getting-started/) for details on how to authenticate with OAuth 2.0.
</Danger>

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](/developer-guides/uxt-getting-started/).

<h3 id="_request_body_2">
  Request body
</h3>

| Fields                                            | Description                                                                                                                         |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| user\_token<br /><br />string<br /><br />Required | Unique identifier of the user account holder.<br /><br />**Allowable Values:**<br /><br />1–36 chars<br /><br />Existing user token |

<h3 id="_sample_request_body_2">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "user_token": "a94c2e7e-9383-4486-9759-8c04cf672e4e"
}
```

<h3 id="_response_body_2">
  Response body
</h3>

| Fields                                                     | Description                                                                                                                          |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| program\_short\_code<br /><br />string<br /><br />Returned | Program short code on the Marqeta platform.<br /><br />**Allowable Values:**<br /><br />Existing program short code                  |
| token<br /><br />string<br /><br />Returned                | Token string to be passed to the UX Toolkit’s `bootstrap()` method.<br /><br />**Allowable Values:**<br /><br />Authentication token |

<h3 id="_sample_response_body_2">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "program_short_code": "myprgrm",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9ncmFtX3Nob3J0X2NvZGUiOiJteXByZ3JtIiwidXNlcl90b2tlbiI6IjE0OWNjYjVmLWUwZDYtNGMwZS05MjAzLWJkMDkyZGI0N2UzNCJ9.6TdyvMOa_eUSvN5GpUZKBOgcHxmWTuYQPMEgNwBfVS0"
}
```

<h2 id="post_theme_by_name">
  Upload theme object
</h2>

**Action:** `POST`\
**Endpoint:** `/theme`

{/* <EndpointCard
title="Upload theme object"
path="/theme"
method="post"
/> */}

Use this endpoint to upload your theme as a JSON object.

Once you have finalized your application’s theme using the [Studio environment](/developer-guides/about-ux-toolkit/#_studio_environment), you can upload it to Marqeta for use with your card product. For details, see [UX Toolkit Getting Started](/developer-guides/uxt-getting-started/).

<h3 id="_request_body_3">
  Request body
</h3>

| Fields                                            | Description                                                                                                                                                                                                                                                       |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| theme<br /><br />object<br /><br />Optional       | Collection of the configurable values that have been defined to create a customized look-and-feel for a card product.<br /><br />**NOTE:** Each card product in your card program can have its own theme.<br /><br />**Allowable Values:**<br /><br />JSON object |
| theme\_name<br /><br />string<br /><br />Optional | Descriptive name used to identify this theme.<br /><br />**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`.<br /><br />**Allowable Values:**<br /><br />1–32 chars     |

<h3 id="_sample_request_body_3">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
    "theme_name": "the-best-card-product",
    "theme": "**Your_JSON_Theme_Object**"
}
```

<h3 id="_sample_response_body_3">
  Sample response body
</h3>

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

```json JSON lines wrap theme={null}
HTTP response code 201
```

For the full list of codes supported by the Marqeta platform, see [HTTP response codes](/core-api/errors/#http-response-codes).

<h2 id="post_card_art">
  Upload card art
</h2>

**Action:** `POST`\
**Endpoint:** `/cardproducts/cardart`

{/* <EndpointCard
title="Upload card art"
path="/cardproducts/cardart"
method="post"
/> */}

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](/developer-guides/about-ux-toolkit/#_studio_environment) and in your application. For details, see [UX Toolkit Getting Started](/developer-guides/uxt-getting-started/).

<h3 id="_request_body_4">
  Request body
</h3>

| Fields                                                     | Description                                                                                                                           |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| card\_product\_token<br /><br />string<br /><br />Required | Unique identifier of the card product.<br /><br />**Allowable Values:**<br /><br />1–36 chars<br /><br />Existing card product token. |
| program\_short\_code<br /><br />string<br /><br />Returned | Program short code on the Marqeta platform.<br /><br />**Allowable Values:**<br /><br />Existing program short code                   |
| asset\_type<br /><br />string<br /><br />Required          | Type of card asset.<br /><br />**Allowable Values:**<br /><br />`front`, `back`, `thumbnail`                                          |
| file<br /><br />string<br /><br />Required                 | Specifies a card art image in PNG format.<br /><br />**Allowable Values:**<br /><br />Portable network graphics file (`*.PNG`)        |

<h3 id="_sample_request_body_4">
  Sample request body
</h3>

```mime MIME expandable lines wrap theme={null}
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>--
```

<h3 id="_sample_response_body_4">
  Sample response body
</h3>

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

```json JSON lines wrap theme={null}
HTTP response code 201
```

For the full list of codes supported by the Marqeta platform, see [HTTP response codes](/core-api/errors/#http-response-codes).

<h2 id="_upload_custom_translation_files">
  Upload custom translation files
</h2>

**Action:** `POST`\
**Endpoint:** `/translations`

<Danger>
  **Important**

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

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](/developer-guides/uxt-getting-started/#_using_custom_translation_files) section in the [UX Toolkit Getting Started](/developer-guides/uxt-getting-started/) guide.

<h3 id="_request_body_5">
  Request body
</h3>

| Fields                                                     | Description                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| program\_short\_code<br /><br />string<br /><br />Required | Program short code on the Marqeta platform.<br /><br />**Allowable Values:**<br /><br />Existing program short code                                                                                                                                                                                          |
| language\_code<br /><br />string<br /><br />Required       | Language code associated to translations.<br /><br />**Allowable Values:**<br /><br />`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<br /><br />object<br /><br />Required         | Object that contains a list of key/value pairs for translations. For a full list of keys, contact your Marqeta onboarding specialist.<br /><br />**Allowable Values:**<br /><br />Valid JSON object                                                                                                          |

<h3 id="_sample_request_body_5">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "program_short_code": "mqtest",
  "language_code": "es-ES",
  "translations": {
      "translation": {
          "activate_card": "Activar tu tarjeta",
          "replace_card": "Reemplazar tu tarjeta"
      }
  }
}
```

<h3 id="_sample_response_body_5">
  Sample response body
</h3>

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

```json JSON lines wrap theme={null}
HTTP response code 201
```

For the full list of codes supported by the Marqeta platform, see [HTTP response codes](/core-api/errors/#http-response-codes)


## Related topics

- [UX Toolkit Overview](/docs/developer-guides/uxt-landing-page.md)
- [About UX Toolkit](/docs/developer-guides/about-ux-toolkit.md)
- [UX Toolkit Getting Started](/docs/developer-guides/uxt-getting-started.md)
- [UX Toolkit Legal Information](/docs/developer-guides/uxt-legal.md)
- [Working with UX Toolkit Web Components](/docs/developer-guides/uxt-web-components.md)