Session Backend

Use this flow when your product embeds VRPlatform UI in an iframe. Your backend issues a session, then passes the returned session payload to the frontend.

Endpoint

POST https://api.edge.vrplatform.app/auth/embed/session

Headers:

x-api-key: <provider-api-key>
Content-Type: application/json

Optional query param:

autoProvision=true

Required Inputs

Field	Meaning
`sub`	your stable external user id
`tenantId`	the managed team the iframe should open into

Example request:

{
  "sub": "hostaway-user-123",
  "tenantId": "4f8f94de-2cc0-4ec7-a7f8-f0c7f560e59a"
}

Use autoProvision=true when first iframe access may happen before that user already exists in VRPlatform.

Response

{
  "accessToken": "<vrplatform-bearer-token>",
  "expiresAt": "2026-04-01T12:00:00.000Z",
  "tenantId": "4f8f94de-2cc0-4ec7-a7f8-f0c7f560e59a",
  "userId": "11111111-1111-4111-8111-111111111111"
}

Current token lifetime is 15 minutes.

Backend Flow

authenticate the user in your own product
decide the target tenantId
call POST /auth/embed/session
return accessToken, expiresAt, and tenantId to the frontend
refresh the session by calling the same endpoint again when it expires

cURL Example

curl -X POST 'https://api.edge.vrplatform.app/auth/embed/session?autoProvision=true' \
  -H 'x-api-key: <provider-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sub": "hostaway-user-123",
    "tenantId": "4f8f94de-2cc0-4ec7-a7f8-f0c7f560e59a"
  }'

Verification

A successful session should produce a bearer token that works on product API calls from the iframe.

curl 'https://api.edge.vrplatform.app/teams/4f8f94de-2cc0-4ec7-a7f8-f0c7f560e59a' \
  -H 'Authorization: Bearer <accessToken>'

Common Failure Cases

Status / Message	Meaning
`401 Missing provider api key`	`x-api-key` was not sent
`401 Invalid provider API key, not found`	provider key is wrong or unknown
`401 Provider API key is inactive`	provider or key is inactive
`401 Provider API key expired`	provider key expired
`404 Tenant not found`	`tenantId` does not exist
`401 Provider API key is not allowed for tenant`	key cannot access that team
`401 Unknown embedded user`	no `(providerId, sub)` user exists and `autoProvision` was not enabled
`401 Embedded user is not active`	embedded user is inactive, archived, or unconfirmed
`401 Embedded user is not allowed to access tenant`	embedded user exists but is not a member of the target tenant

Next Step

After this works, wire the returned session into the frontend flow described in iFrames.

Session Backend

On this page