> ## Documentation Index
> Fetch the complete documentation index at: https://embedded-apps.rollout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mint user tokens

> Sign a short-lived token on your server for the user signed in to your CRM.

Rollout's components act for one user of your CRM. Your server proves who that
user is by signing a **user token**, a JWT, which your page fetches from your
server and hands to the components.

You'll add two endpoints:

| Endpoint | Scopes | For |
| - | - | - |
| A per-contact token | `embed:render` | `mountEmbeddedApps()`, to show the apps on one contact |
| A marketplace token | `embed:enable`, and `embed:enable_org` for org admins | `mountEmbeddedAppMarketplace()`, or the marketplace API |

## The token endpoints

Mint tokens on your server, for the user signed in to your session, never in
the browser. The person claims describe one contact, so the apps component asks
for a token per contact, and tells you which. The marketplace needs no person.

```ts theme={null}
// Node, with the jsonwebtoken package
import jwt from "jsonwebtoken";

function mintToken(user, scopes, person) {
  return jwt.sign(
    {
      sub: String(user.id),
      "rollout.com": {
        scopes,
        embed: {
          ...(user.officeId && { org: String(user.officeId) }),
          user: { name: user.name, email: user.email },
          ...(person && {
            person: {
              id: String(person.id),
              ...(person.firstName && { firstName: person.firstName }),
              ...(person.lastName && { lastName: person.lastName }),
              ...(person.stageId && {
                stage: { id: String(person.stageId), name: person.stageName },
              }),
            },
          }),
        },
      },
    },
    process.env.ROLLOUT_CLIENT_SECRET,
    {
      algorithm: "HS256",
      issuer: process.env.ROLLOUT_TENANT_ID,
      expiresIn: "10m",
    },
  );
}

// For mountEmbeddedApps(), per contact.
app.get("/rollout/apps-token", requireSignedIn, async (req, res) => {
  const person = await loadContactTheUserCanSee(req.user, String(req.query.personId));
  if (!person) return res.sendStatus(404);
  res.type("text/plain").send(mintToken(req.user, ["embed:render"], person));
});

// For mountEmbeddedAppMarketplace(), or your own marketplace.
app.get("/rollout/marketplace-token", requireSignedIn, (req, res) => {
  const scopes = ["embed:enable", ...(req.user.isOrgAdmin ? ["embed:enable_org"] : [])];
  res.type("text/plain").send(mintToken(req.user, scopes));
});
```

> [!WARNING]
>
> The contact id comes from the browser, so check that the user may see that
> contact before you sign a token for it.

Keep tokens short-lived. The components ask for a fresh one whenever they need
it, so ten minutes is plenty.

## Claims

```json theme={null}
{
  "iss": "YOUR_TENANT_ID",
  "sub": "AG123",
  "iat": 1762790400,
  "exp": 1762794000,
  "rollout.com": {
    "scopes": ["embed:render"],
    "embed": {
      "org": "site_123",
      "user": { "name": "Sawyer Agent", "email": "sawyer@example.com" },
      "account": {
        "domain": "sawyer-realty",
        "owner": { "name": "Pat Broker", "email": "pat@example.com" }
      },
      "person": {
        "id": "YOUR_CONTACT_ID",
        "firstName": "Melissa",
        "lastName": "Hartman",
        "stage": { "id": "12", "name": "Active Client" }
      }
    }
  }
}
```

| Claim | Required | Meaning |
| - | - | - |
| `iss` | Yes | Your tenant id (your client id). |
| `sub` | Yes | Your own id for the user, as a string. Apps receive it as `user.id`. Keep it stable: the apps a user turns on are stored against it. |
| `iat`, `exp` | Yes | Issued at and expiry, in seconds. `exp` can be **at most one hour** from now. |
| `rollout.com.scopes` | Yes | What the token lets the user do. See [Token scopes](#token-scopes). |
| `rollout.com.embed.org` | No, but send it | Your id for the user's org, such as an office, team or site. Apps receive it as `org.id` and `crm.accountId`. Send it in **every** token, the render token included: an app turned on for an org shows only to users whose token names that org. It's also required to turn apps on for an org. |
| `rollout.com.embed.user` | No | `name` and `email` of the user, passed to apps. |
| `rollout.com.embed.account` | No | `domain` of the CRM account, and its `owner` (`name` and `email`), all required if you send `account`. Passed to apps. |
| `rollout.com.embed.person` | No | The contact on screen: `id` (required), and optionally `firstName`, `lastName` and `stage` (`id` and `name`). Passed to apps only when `person.id` is the id of the contact being rendered. |

Every id and value is a string. Leave out a key you have no value for rather
than sending `null`, and send `stage` only with both its `id` and `name`. A
claim of the wrong shape fails the whole token with `INVALID_EMBED_CLAIMS`, or
`INVALID_TOKEN_DATA` for a `sub` that isn't a string.

Rollout ignores keys it doesn't know in `embed`. Don't send the person's emails
or phone numbers: no app receives them.

## Signing

Sign the token with your client secret using **HS256**, HS384 or HS512. Rollout
accepts any of your tenant's active client secrets, so tokens keep working
while you rotate one.

## Token scopes

| Scope | Lets the user | Needed by |
| - | - | - |
| `embed:render` | See their enabled apps on a contact. | `mountEmbeddedApps()` |
| `embed:enable` | Turn apps on and off for themselves, and list the marketplace's apps. | `mountEmbeddedAppMarketplace()` and the [marketplace API](https://embedded-apps.rollout.com/reference/marketplace-api.md) |
| `embed:enable_org` | Turn apps on and off for the org named in `embed.org`. Grant it, with `embed:enable`, to your org admins only. | The org switches |

A token with any `embed:*` scope is accepted **only** by the embedded apps.
The Universal API refuses it (`403 EMBED_TOKEN_NOT_ACCEPTED`), so a script on
your page can't use it to read or connect anyone's accounts. If you also use the
Universal API, mint separate tokens for it, without embed scopes.

## Next

[Show the apps on a contact](https://embedded-apps.rollout.com/build/show-apps.md), with the per-contact token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.