---
title: "Create card embed session"
method: POST
path: "/v1/cards/{card_token}/embed"
tags: ["Card"]
---

# Create card embed session

`POST /v1/cards/{card_token}/embed`

Creates a short-lived session for displaying card details or setting a card PIN in
Lithic-hosted iframes. Create the session on your backend to not expose your API key in browser code.

A session token can only be used to reveal card details (per embed type) or submit a pin a single time. Attempting to
re-use session tokens will result in 401's.

## Path parameters

- `card_token` string, uuid, required

## Request body

- CreateEmbedSessionRequest — Parameters for creating a short-lived card embed session.
  - `type` 'CARD_EMBED' | 'PIN_SETTING_EMBED', required — The type of card embed session to create. `CARD_EMBED` sessions can load `PAN`, `CVV`, `EXP_MONTH`, and `EXP_YEAR` iframes. `PIN_SETTING_EMBED` sessions can load only the `PIN_SETTING` iframe.
  - `expiration` integer — Unix timestamp at which the session expires. The value must be in the future and no more than 10 minutes after the request. If omitted, the session expires 10 minutes after the request.
  - `max_pin_length` integer — Maximum number of digits accepted by a `PIN_SETTING_EMBED`. The value must be from 4 through 8 and defaults to 8. This parameter is not supported for `CARD_EMBED` sessions and will be rejected
  - `target_origin` string, uri, required — Canonical HTTPS origin of the page that will embed the iframe. Lithic embeds will verify the `target_origin` against the parent application's origin. The origin must not contain a path, query parameters, fragment, or credentials.

## Response `200`

A short-lived card embed session.

- EmbedSessionResponse — A short-lived session used to load Lithic-hosted card embed iframes.
  - `session` string, required — Opaque, short-lived credential used to load card embed iframes. Treat this value as sensitive. Do not log, persist, include in analytics, or share it.

## Other responses

- `400` — A parameter in the query given in the request does not match the valid queries for the endpoint.
- `401` — | | | |---|---| | User has not been authenticated | Invalid or missing API key | | API key is not active | The API key used is no longer active | | Could not find API key | The API key provided is not associated with any user | | Please provide API key in Authorization header | The Authorization header is not in the request | | Please provide API key in the form Authorization: [api-key] | The Authorization header is not formatted properly | | Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Reach out at [lithic.com/contact](https://lithic.com/contact) | | Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege | Reach out at [lithic.com/contact](https://lithic.com/contact) |
- `404` — The specified resource was not found.
- `422` — Unprocessable entity.
- `429` — Client has exceeded the number of allowed requests in a given time period. | | | |---|---| | Rate limited, too many requests per second | User has exceeded their per second rate limit | | Rate limited, reached daily limit | User has exceeded their daily rate limit | | Rate limited, too many keys tried | One IP has queried too many different API keys |

---

[API](https://skmtc.net/lithic-com/apis/lithic-developer-api.md) · [All operations](https://skmtc.net/lithic-com/apis/lithic-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lithic-com/lithic-developer-api/revisions/53ab5d4e2adb/schema)