> For the complete documentation index, see [llms.txt](https://docs.cloutly.com/reviews-sdk-for-marketplace-websites/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloutly.com/reviews-sdk-for-marketplace-websites/cloutly-embed/system-overview-1.md).

# Provision Users

This flow is modeled after a provision-first embed architecture: your backend signs a short-lived JWT, Cloutly verifies it, then upserts user and business context automatically before loading the iframe.

## Step 1: Obtain your signing key

In Cloutly platform settings, manually create/retrieve your embed signing key.

> Keep this key server-side only. Never expose it in browser code.

## Step 2: Generate a short-lived JWT on your backend

Use your signing key to create a JWT that includes identity and business context.

### Required claims

```json
{
  "externalUserEmail": "owner@acme.com",
  "externalBusinessId": "biz_123",
  "businessDisplayName": "Acme Plumbing - Gold Coast",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "ADMIN",
  "smsLimits": 500,
  "iat": 1735689600,
  "exp": 1735689900
}
```

### Claim notes

* `externalUserEmail` is used to upsert the user.
* `externalBusinessId` is used to upsert the business.
* `businessDisplayName` is used for readable business labels in UI.
* `role` controls access inside embed session.
* `smsLimits` sets available SMS capacity for this business context.
* Use short TTLs for `exp` and issue tokens per active session.

## Step 3: Pass token into iframe session

Your frontend requests a token from your backend, then appends it to the embed URL as a session bootstrap token.

```mermaid
sequenceDiagram
  participant Browser as Your Frontend
  participant Backend as Your Backend
  participant Cloutly as Cloutly Embed

  Browser->>Backend: GET /embed/token?businessId=biz_123
  Backend-->>Browser: signed JWT
  Browser->>Cloutly: Load iframe with token
  Cloutly->>Cloutly: Verify token signature
  Cloutly->>Cloutly: Upsert user and business
  Cloutly-->>Browser: Embedded app rendered
```