HTTP endpoints
createEmbedSession
Start an embedded partner dashboard session. Load the returned url in an iframe once. Its start token works one time and expires with the session. ttlSeconds accepts 60 to 600 and defaults to 600. Needs embed:write.
POST /api/v1/embed/sessions
Requires embed:write. Keep the Bearer key on your server.
Send placement or programIds, or omit both for an unrestricted session. layout defaults to full whether or not you send a placement. New placement enrollments require an active program and share the session transaction.
SDK
grizzlee.createEmbedSession(input: { partner: { externalId: string; } | { id: string; }; programIds?: string[] | undefined; locale?: "en" | "fr-CA" | "hy" | "ru" | undefined; layout?: "full" | "simple" | undefined; actions?: ("payout_details:write" | "profile:write")[] | undefined; ttlSeconds?: number | undefined; embedOrigin?: string | undefined; placement?: string | undefined; }): Promise<CreateEmbedSessionResponse>HTTP
Use your backend's HTTP client. The cURL request shows the wire format. Replace path parameters and example values.
curl --fail-with-body --request POST \
'https://app.grizzlee.ca/api/v1/embed/sessions' \
-H "Authorization: Bearer $GRIZZLEE_SERVER_KEY" \
-H 'Content-Type: application/json' \
--data '{"partner":{"externalId":"merchant-partner-001"}}'Request body
| Field | Type | Required | Details |
|---|---|---|---|
partner | union | Yes | |
locale | "en", "fr-CA", "hy", "ru" | No | |
layout | "full", "simple" | No | default "full" |
actions | array | No | default [] |
ttlSeconds | integer | No | minimum 60. maximum 600. default 600 |
embedOrigin | string | No | uri |
placement | string | No | |
programIds | array | No |
partner
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
partner.externalId | string | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
partner.id | string | Yes |
Request schema
{
"type": "object",
"properties": {
"partner": {
"anyOf": [
{
"type": "object",
"properties": {
"externalId": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"required": [
"externalId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"required": [
"id"
],
"additionalProperties": false
}
]
},
"locale": {
"type": "string",
"enum": [
"en",
"fr-CA",
"hy",
"ru"
]
},
"layout": {
"type": "string",
"enum": [
"full",
"simple"
],
"default": "full"
},
"actions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"payout_details:write",
"profile:write"
]
},
"maxItems": 2,
"default": []
},
"ttlSeconds": {
"type": "integer",
"minimum": 60,
"maximum": 600,
"default": 600
},
"embedOrigin": {
"type": "string",
"format": "uri"
},
"placement": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{1,62}$"
},
"programIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"minItems": 1
}
},
"required": [
"partner"
],
"additionalProperties": false
}Response
HTTP responses wrap this value in data. The SDK returns the value directly unless the note above describes a wrapper.
| Field | Type | Required | Details |
|---|---|---|---|
url | string | Yes | Load this URL in the iframe once. The start token is in the fragment and works one time. |
id | string | Yes | |
partnerId | string | Yes | |
partnerExternalId | string | Yes | |
programIds | union | Yes | Null includes all programs. Otherwise only these memberships are visible. |
placement | union | Yes | |
locale | union | Yes | |
layout | union | Yes | |
actions | array | Yes | |
embedOrigin | union | Yes | The parent page origin the merchant expects, or null when the session allows any listed origin. |
expiresAt | string | Yes | |
createdAt | string | Yes | |
consumedAt | union | Yes | When the frame exchanged the start token. |
revokedAt | union | Yes |
programIds
Variant 1
Type: null.
Variant 2
Type: array.
placement
Variant 1
Type: null.
Variant 2
Type: string.
locale
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
layout
Variant 1
Type: string.
Variant 2
Type: string.
actions[]
Variant 1
Type: string.
Variant 2
Type: string.
embedOrigin
Variant 1
Type: null.
Variant 2
Type: string.
consumedAt
Variant 1
Type: null.
Variant 2
Type: string.
revokedAt
Variant 1
Type: null.
Variant 2
Type: string.
Response schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Load this URL in the iframe once. The start token is in the fragment and works one time."
},
"id": {
"type": "string"
},
"partnerId": {
"type": "string"
},
"partnerExternalId": {
"type": "string"
},
"programIds": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Null includes all programs. Otherwise only these memberships are visible."
},
"placement": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"locale": {
"anyOf": [
{
"type": "string",
"const": "en"
},
{
"type": "string",
"const": "fr-CA"
},
{
"type": "string",
"const": "hy"
},
{
"type": "string",
"const": "ru"
}
]
},
"layout": {
"anyOf": [
{
"type": "string",
"const": "full"
},
{
"type": "string",
"const": "simple"
}
]
},
"actions": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"const": "payout_details:write"
},
{
"type": "string",
"const": "profile:write"
}
]
}
},
"embedOrigin": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "The parent page origin the merchant expects, or null when the session allows any listed origin."
},
"expiresAt": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"consumedAt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "When the frame exchanged the start token."
},
"revokedAt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
}
},
"required": [
"url",
"id",
"partnerId",
"partnerExternalId",
"programIds",
"placement",
"locale",
"layout",
"actions",
"embedOrigin",
"expiresAt",
"createdAt",
"consumedAt",
"revokedAt"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.