Embed Tokens

Create, list and revoke the tokens that open one pass template inside an iframe of your own application.

Your server creates a token with this API and your page loads the returned embedUrl in an iframe. The user works with the template right there, without an account and without signing in to Passcreator. The token decides which template, which tabs and which actions the embedded view offers. How to build the page around the iframe, how the iframe talks to your page and how a session ends is described in the integration guide.

The embedded feature must be enabled for your account. Contact support@passcreator.com to enable it.
Your account needs a custom domain on the same site as the page that embeds the iframe (see embeddingOrigin below). If it has none yet, request a White Label Domain in Passcreator under Subscription › Additional Services.
Tokens are created with the API key of a user of your account. That user's permissions are the upper limit of everything a token can grant.
Create tokens on your server only. Never send your API key to a browser.

POST/api/v3/embed/token

Create an Embed Token

Creates a single-use token for one pass template and returns it together with the URL to load in the iframe.

The token only has to last until the iframe opens it. Opening it starts an embed session in the user's browser; from then on the session carries the user, also when the iframe is reloaded. A token can be opened once.

URL Parameters

This endpoint has no path or query parameters.

Example URL

Request URL

https://app.passcreator.com/api/v3/embed/token

Authorization

For authorization you need to add a HTTP header to your request:

Name
Authorization
Type
string
(mandatory)
Description
HTTP header that contains the API key of the user who creates the token. Replace yourApiKeyHere with that API key.
It must be a regular API key of a user of your account that has not expired. The token can only grant what this user may do (see Capabilities).

Example HTTP Header

HTTP header with authorization

    POST /api/v3/embed/token HTTP/1.1
    Host: app.passcreator.com
    Authorization: yourApiKeyHere
    Content-Type: application/json
    ...

Request Body

The following properties of the data object can/must be submitted in the request body. Numbers must be sent as JSON numbers, not as strings.

Name
templateId
Type
string
(mandatory)
Description
The ID of the pass template to open. It must be a template of your account and must not be archived. Replace yourTemplateId in the examples with it.
Name
embeddingOrigin
Type
string
(mandatory)
Description
The origin of the page that embeds the iframe, exactly in the form https://host or https://host:port: no path, no query, no wildcard. Only a page on this origin can frame the embedded view, and the view only exchanges messages with this origin.
The host must be on the same site as your custom domain: the custom domain's parent domain or a subdomain of it. With the custom domain passes.example.com, the origins https://example.com and https://app.example.com are accepted, https://example.org is not. The custom domain needs a parent domain of at least two labels (passes.example.com works, example.com does not).
The value is normalised (lowercase, default port and trailing slash removed) and returned in that form.
Name
capabilities
Type
object
(mandatory)
Description
The tabs and actions the embedded view offers, as an object with the keys tabs and actions. There is no default. Every value is explained in Capabilities.
Name
capabilities.tabs
Type
array<string>
(mandatory)
Description
The tabs to show. Must contain overview; no duplicates.
Allowed values: overview, passes, distribution, activity, analytics, settings.
Name
capabilities.actions
Type
array<string>
(optional)
Description
Default: []
The actions to allow; without actions the view is read-only. No duplicates.
Allowed values: createPass, editTemplate, publish, sendPush (each needs the tab overview) and updatePass, deletePass, sendPass (each needs the tab passes).
Name
language
Type
enum<"en", "de", "fr", "es", "is", "el", "pt">
(optional)
Description
The language of the embedded view: its texts and its date and number formats.
Always send it. Without it, the texts follow the language of the user's browser while dates and numbers fall back to English formats.
Name
metadata
Type
object
(optional)
Description
Default: null
Information about the user of your application who opens the view, stored with the token for attribution. Allowed keys: externalUserId, externalUserName, reference; if you send the object, it needs at least one of them. Each value is a non-empty string of printable characters with at most 200 characters.
The metadata is never used to decide what the user may do.
Name
expiresIn
Type
integer
(optional)
Description
Default: 600
Seconds until the token expires if the iframe has not opened it. Allowed: 60 to 3600. Create the token right before you render the iframe.
Name
sessionLifetime
Type
integer
(optional)
Description
Default: 28800 (8 hours)
Seconds the embed session lasts after the iframe opened the token. Allowed: 300 to 28800. The end is absolute; there is no timeout for inactivity.

Example Request Body

Request body

{
  "data": {
    "templateId": "yourTemplateId",
    "embeddingOrigin": "https://app.example.com",
    "capabilities": {
      "tabs": ["overview", "passes"],
      "actions": ["createPass", "updatePass"]
    },
    "language": "en",
    "metadata": {
      "externalUserId": "4711",
      "externalUserName": "Jane Doe"
    }
  }
}

Request Examples

Replace yourApiKeyHere with the API key of the user who creates the token and yourTemplateId with the ID of your pass template.

Create an embed token

POST

/api/v3/embed/token

curl -X POST https://app.passcreator.com/api/v3/embed/token \
  -H "Authorization: yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "templateId": "yourTemplateId",
      "embeddingOrigin": "https://app.example.com",
      "capabilities": {"tabs": ["overview", "passes"], "actions": ["createPass", "updatePass"]},
      "language": "en",
      "metadata": {"externalUserId": "4711"}
    }
  }'

Returned values

On success the endpoint answers 201. The data object contains:

Name
id
Type
string
(mandatory)
Description
The ID of the token. Use it to revoke the token.
Name
templateId
Type
string
(mandatory)
Description
The ID of the pass template the token opens.
Name
embeddingOrigin
Type
string
(mandatory)
Description
The normalised origin that may embed the view.
Name
capabilities
Type
object
(mandatory)
Description
The granted tabs and actions, without duplicates and in the order of the lists in Capabilities.
Name
metadata
Type
object | null
(mandatory)
Description
The metadata as sent.
Name
language
Type
string | null
(mandatory)
Description
The language as sent.
Name
createdAt
Type
string
(mandatory)
Description
Creation time in ISO 8601 format (UTC).
Name
expiresAt
Type
string
(mandatory)
Description
Time after which the token can no longer be opened.
Name
sessionLifetime
Type
integer
(mandatory)
Description
The session length in seconds.
Name
usedAt
Type
string | null
(mandatory)
Description
Time the iframe opened the token; null until then.
Name
sessionExpiresAt
Type
string | null
(mandatory)
Description
Absolute end of the embed session; null until the token is opened.
Name
revokedAt
Type
string | null
(mandatory)
Description
Time the token was revoked; null if it was not.
Name
embedToken
Type
string
(mandatory)
Description
The token itself (64 letters and digits). It is returned only in this response; store it nowhere and use it only in embedUrl.
Name
embedUrl
Type
string
(mandatory)
Description
The URL to load in the iframe, on your custom domain: https://passes.example.com/embedded?token=…. You can append &view= with a granted tab to open it first, e.g. &view=passes.

Example Response

Response Examples

{
  "statusCode": 201,
  "success": true,
  "description": "",
  "errors": [],
  "count": 14,
  "responseMetaData": null,
  "data": {
    "id": "6f1c2a7e-3b9d-4c55-9a0e-2d7b8e41f0c3",
    "templateId": "0d4e9b62-58a1-4f3c-b7e2-91c5a3d8f604",
    "embeddingOrigin": "https://app.example.com",
    "capabilities": {
      "tabs": ["overview", "passes"],
      "actions": ["createPass", "updatePass"]
    },
    "metadata": {
      "externalUserId": "4711",
      "externalUserName": "Jane Doe"
    },
    "language": "en",
    "createdAt": "2026-10-09T10:00:00+00:00",
    "expiresAt": "2026-10-09T10:10:00+00:00",
    "sessionLifetime": 28800,
    "usedAt": null,
    "sessionExpiresAt": null,
    "revokedAt": null,
    "embedToken": "2LICvPEOzQXjniZpb6yBZcdmz5YfjnRIsceD9PuAEGPZ9t8Ku0Oa0D8xTmRiaREt",
    "embedUrl": "https://passes.example.com/embedded?token=2LICvPEOzQXjniZpb6yBZcdmz5YfjnRIsceD9PuAEGPZ9t8Ku0Oa0D8xTmRiaREt"
  }
}

Errors

An error response names exactly one error key in errors. The request is checked in a fixed order and the first failing check answers; fix it and send the request again to see the next one.

Status	Error key	Cause
400	invalidCapabilities	capabilities is missing or not an object, has keys other than tabs and actions, contains an unknown or duplicate value, lacks the tab overview, or grants an action without its tab.
400	capabilityNotGrantedToCreator	The user whose API key creates the token lacks a permission that a requested tab or action needs (see Capabilities).
400	invalidEmbeddingOrigin	embeddingOrigin is not of the form https://host[:port], its host is not a domain name, or it is not on the same site as your custom domain.
400	noVanityHost	Your account has no custom domain.
400	vanityHostTooShort	Your custom domain has no parent domain of at least two labels.
400	invalidExpiresIn	expiresIn is not a whole number between 60 and 3600.
400	invalidSessionLifetime	sessionLifetime is not a whole number between 300 and 28800.
400	invalidMetadata	metadata is not an object, is empty, has another key, or a value is not a non-empty printable string of at most 200 characters.
400	invalidLanguage	language is not one of the supported values.
401	No active customer could be resolved for the provided credentials.	The API key is missing or invalid.
403	featureNotEnabled	The embedded feature is not enabled for your account.
403	apiKeyNotAllowed	The API key is not a regular API key of a user of your account, or it has expired.
404	templateNotFound	templateId is missing, malformed, unknown, archived, or belongs to another account.
500	internalError	An unexpected error. Try again; contact support@passcreator.com if it persists.

Capabilities

The capabilities of a token decide which tabs the embedded view shows and which actions the user can take there. Everything not listed is hidden in the view and refused by the server.

A capability never grants more than the user who creates the token may do. For every requested tab and action, that user needs the permissions listed below; otherwise the request fails with capabilityNotGrantedToCreator.
The permissions are checked when the token is created. Changing the user's role later does not change tokens that already exist; revoke them if a change must apply at once.

Tabs

Tab	Shows	Permissions of the creating user
overview	The template's overview with the pass preview. Always required.	Pass templates: Show existing
passes	The passes of the template.	Passes: Show existing
distribution	The ways to distribute passes of the template, such as landing pages.	Pass templates: Show existing; Landing pages: Show existing
activity	The scheduled push notifications of the template.	Pass templates: Show existing; Pass templates: Send Push Notifications
analytics	The statistics of the template.	Pass templates: Show existing
settings	The settings of the template.	Pass templates: Show existing

Actions

Action	Allows	Needs tab	Permission of the creating user
createPass	Creating passes.	overview	Passes: Create
updatePass	Editing existing passes, including a push notification to a single pass.	passes	Passes: Edit
deletePass	Deleting passes.	passes	Passes: Delete
sendPass	Sending a pass by e-mail or text message while creating or editing it.	passes	Passes: Send pass
editTemplate	Editing the template; changes are saved as a draft, which the user can also discard.	overview	Pass templates: Edit
publish	Publishing the draft, so that the changes reach all passes, optionally with a visible message to their holders.	overview	Pass templates: Send changes
sendPush	Sending push notifications to all passes of the template or to segments.	overview	Pass templates: Send Push Notifications

editTemplate and publish are independent. With editTemplate alone, the user's changes stay a draft until someone publishes them outside the embedded view.
Every publish updates the passes on the devices silently. With publish the user can also add a visible message to it, just as users of Passcreator can with the permission to send changes; sendPush is not needed for that.
The server decides per request which of the two a pass write needs: a request that names a pass needs updatePass and never creates a pass, a new pass needs createPass.
A push notification to a single pass is an edit of that pass: it needs updatePass, not sendPush, just as users of Passcreator need the permission to edit passes for it.

GET/api/v3/embed/token

List Embed Tokens

Lists the tokens of your account that can still be opened or whose session may still be running, newest first. Revoked tokens are included until then, so that you can see them. The token itself (embedToken) and the embedUrl are never returned here.

Optional Query Parameters

Name
templateId
Type
string
(optional)
Description
Only list the tokens of this pass template. Replace yourTemplateId with the ID of your pass template.

Example URLs

Request URL without parameter

https://app.passcreator.com/api/v3/embed/token

Request URL with parameter

https://app.passcreator.com/api/v3/embed/token?templateId=yourTemplateId

Authorization

For authorization you need to add a HTTP header to your request:

Name
Authorization
Type
string
(mandatory)
Description
HTTP header that contains an API key of your account. Replace yourApiKeyHere with your API key.

Example HTTP Header

HTTP header with authorization

    GET /api/v3/embed/token HTTP/1.1
    Host: app.passcreator.com
    Authorization: yourApiKeyHere
    ...

Returned values

data is an array of token objects with the same properties as in the response of Create an Embed Token, without embedToken and embedUrl. count is the number of listed tokens.

Errors

Status	Error key	Cause
401	No active customer could be resolved for the provided credentials.	The API key is missing or invalid.
404	templateNotFound	templateId is malformed, unknown, or belongs to another account.

Example Response

Success

{
  "statusCode": 200,
  "success": true,
  "description": "",
  "errors": [],
  "count": 1,
  "responseMetaData": null,
  "data": [
    {
      "id": "6f1c2a7e-3b9d-4c55-9a0e-2d7b8e41f0c3",
      "templateId": "0d4e9b62-58a1-4f3c-b7e2-91c5a3d8f604",
      "embeddingOrigin": "https://app.example.com",
      "capabilities": {
        "tabs": ["overview", "passes"],
        "actions": ["createPass", "updatePass"]
      },
      "metadata": {
        "externalUserId": "4711",
        "externalUserName": "Jane Doe"
      },
      "language": "en",
      "createdAt": "2026-10-09T10:00:00+00:00",
      "expiresAt": "2026-10-09T10:10:00+00:00",
      "sessionLifetime": 28800,
      "usedAt": "2026-10-09T10:00:04+00:00",
      "sessionExpiresAt": "2026-10-09T18:00:04+00:00",
      "revokedAt": null
    }
  ]
}

DELETE/api/v3/embed/token/{tokenId}

Revoke an Embed Token

Revokes a token. A token that has not been opened yet can no longer be opened; a running embed session that was started with it ends on its next request. Revoking a token twice is harmless: the answer is the same and revokedAt keeps the time of the first revocation.

Path Parameters

Name
tokenId
Type
string
(mandatory)
Description
The id of the token, as returned when it was created or listed. Replace yourTokenId with it.

Example URL

Request URL

https://app.passcreator.com/api/v3/embed/token/yourTokenId

Authorization

For authorization you need to add a HTTP header to your request:

Name
Authorization
Type
string
(mandatory)
Description
HTTP header that contains an API key of your account. Replace yourApiKeyHere with your API key.

Example HTTP Header

HTTP header with authorization

    DELETE /api/v3/embed/token/yourTokenId HTTP/1.1
    Host: app.passcreator.com
    Authorization: yourApiKeyHere
    ...

Returned values

data is the revoked token with the same properties as in the response of Create an Embed Token, without embedToken and embedUrl.

Errors

Status	Error key	Cause
401	No active customer could be resolved for the provided credentials.	The API key is missing or invalid.
404	tokenNotFound	The token ID is malformed, unknown, or belongs to another account.

Example Response

Success

{
  "statusCode": 200,
  "success": true,
  "description": "",
  "errors": [],
  "count": 12,
  "responseMetaData": null,
  "data": {
    "id": "6f1c2a7e-3b9d-4c55-9a0e-2d7b8e41f0c3",
    "templateId": "0d4e9b62-58a1-4f3c-b7e2-91c5a3d8f604",
    "embeddingOrigin": "https://app.example.com",
    "capabilities": {
      "tabs": ["overview", "passes"],
      "actions": ["createPass", "updatePass"]
    },
    "metadata": {
      "externalUserId": "4711",
      "externalUserName": "Jane Doe"
    },
    "language": "en",
    "createdAt": "2026-10-09T10:00:00+00:00",
    "expiresAt": "2026-10-09T10:10:00+00:00",
    "sessionLifetime": 28800,
    "usedAt": "2026-10-09T10:00:04+00:00",
    "sessionExpiresAt": "2026-10-09T18:00:04+00:00",
    "revokedAt": "2026-10-09T11:30:00+00:00"
  }
}