Create an Elements widget session
Mints a short-lived JWT session token authorising one Elements widget
instance for one identified subject. The token is delivered to the
widget shell via the host page or app, then forwarded to DoorFlow.
Tokens expire after 15 minutes; long-lived widgets refresh by
calling this endpoint again from the host backend.
The member block is the integrator's CRM-side identity for the
person; DoorFlow find-or-creates a Person against external_id
on the authenticated account.
/api/3/element_sessions
Authentication
This endpoint requires authentication:
Use an OAuth 2.0 access token in the Authorization header. This is the recommended authentication method for all integrations. OAuth provides automatic token expiration, granular permission scopes, detailed usage tracking, and per-integration revocation. Learn how to obtain an access token.
Header Format:
Authorization: Bearer YOUR_ACCESS_TOKEN
Request Body
widget_type
string
Which widget kind this session authorises. `admin` exposes credential issue/revoke and group management; `member` exposes wallet provisioning and self-deactivation.
member
object
Show child attributes
external_id
string
required
eg. u_42
The integrator's CRM-side identifier for the person. DoorFlow stores this on `Person.organisation_id` and uses it for find-or-create on subsequent calls.
name
string
eg. Alice Smith
Person's full name. Used when creating a new Person record.
email
string
eg. alice@example.com
Person's email. Used when creating a new Person and to claim an existing unlinked Person with the same email.
identity_assertion
string
Optional partner-signed JWT (RFC 7521 / RFC 7523) carrying verified-identity claims. When present and verified against the partner's published JWKS, downstream wallet provisioning may skip its own SMS verification step.
platform
string
Optional platform hint. Only honoured by the iOS-side `/sdk/button` host page; ignored by the JS shell.
config
object
Theme and widget-configuration flags. Each value is validated on the server; invalid values fall back to defaults rather than rejecting the session.
Show child attributes
theme
string
accent_color
string
eg. #FF6600
3- or 6-digit hex (e.g. `#FF6600`).
border_radius
integer
font_family
string
eg. Inter, -apple-system, sans-serif
CSS font-family stack. Restricted to letters, digits, hyphens, spaces, commas, and single quotes.
manage_groups
boolean
show_member
boolean
credentials
array
Optional explicit credential-type slugs (or well-known aliases) to expose in the widget. Defaults to all wallet-eligible types for the requested widget kind.
Example
{
"widget_type": "member",
"member": {
"external_id": "u_42",
"name": "Alice Smith",
"email": "alice@example.com"
},
"identity_assertion": "string",
"platform": "string",
"config": {
"theme": "string",
"accent_color": "#FF6600",
"border_radius": 0,
"font_family": "Inter, -apple-system, sans-serif",
"manage_groups": false,
"show_member": false
},
"credentials": [
"string"
]
}Responses
Session token minted successfully
Response Fields
token
string
required
Short-lived JWT to forward to the widget shell.
eg. eyJhbGciOiJIUzI1NiJ9...
expires_in
integer
required
Seconds until the token expires.
eg. 900
Unauthorized - Invalid or missing authentication
Response Fields
error
string
eg. unauthorized
error_description
string
eg. The access token is invalid
Forbidden - User does not have permission
Response Fields
error
string
eg. forbidden
error_description
string
eg. You are not authorized to access this resource
Session could not be minted — typed error in the response body
Response Fields
error
string
required
Typed error code so SDK callers can branch without parsing the human-readable message.
message
string
Human-readable description of the error.
Identity-assertion verification could not complete because the partner JWKS endpoint was unreachable
Response Fields
error
string
required
Typed error code so SDK callers can branch without parsing the human-readable message.
message
string
Human-readable description of the error.
Internal Server Error
Response Fields
error
string
eg. internal_server_error
error_description
string
eg. An unexpected error occurred