Widgets let your application embed an Authdog-managed surface while your backend controls which user or organization it can act for. Integration starts by minting a short-lived widget token; do not expose a long-lived API credential to the browser.

Widgets are not the hosted [Account Portal](/docs/account-portal). Account Portal sends an end user to Authdog-hosted account screens. A widget is initialized inside your application with a narrowly scoped token.

## Plan the widget context

Before issuing a token, decide:

- Which environment owns the data.
- Which `userId` or `organizationId` the widget should act for. At least one is required.
- Which widget capabilities it needs.

Example requested scope names include `users-management` and `organization-switcher`. Authdog namespaces requested values as `widgets:<scope>`. If you omit scopes, the token receives `widgets:default`.

## Mint a token on your backend

Call the authenticated REST API from server code:

```http
POST /v1/tenants/{tenantId}/environments/{environmentId}/widgets/token
Authorization: Bearer <server-held-token>
Content-Type: application/json

{
  "organizationId": "org_123",
  "userId": "user_456",
  "scopes": ["organization-switcher"]
}
```

The response contains `token`, `expiresAt`, and normalized `scopes`. Widget tokens expire after **10 minutes**.

Token claims identify the token as a widget token (`typ: widget`, audience `widgets`) and bind it to the selected environment. They are signed with that environment's active signing key.

## Initialize and refresh

1. Authenticate the user in your application.
2. Authorize their access to the requested user or organization.
3. Ask your backend for a widget token.
4. Pass only that short-lived token to your supported widget integration.
5. Mint a replacement before or after expiry when the widget remains open.

Do not copy a public widget initialization URL or package name from an unrelated example. Use the initializer supplied by the specific Authdog widget integration you are installing; token generation is the common server-side contract documented here.

## Security guidance

- Never mint tokens directly in browser code. The REST call requires a privileged bearer token.
- Derive `userId`, `organizationId`, and scopes from authenticated server-side state, not unchecked request fields.
- Grant only scopes required by the mounted widget.
- Do not use a widget token as an application session. Its token type and audience are intentionally separate.
- Do not persist tokens in local storage or logs. Keep them in memory and replace them on expiry.
- Never reuse a token across environments or organizations.

Token creation fails when neither `userId` nor `organizationId` is present, when authentication fails, or when the environment has no active signing key.

## Operational notes

- Refresh on expiry rather than increasing token lifetime; lifetime is fixed by the issuer.
- Re-mint when active organization or user context changes.
- Inspect returned `scopes` when debugging. Authdog adds the `widgets:` namespace.
- A successful mint proves only that token issuance worked. Test widget behavior with the intended identity and organization.

## Related

- [Components](/docs/components) — authentication UI mounted in your application
- [Account Portal](/docs/account-portal) — hosted end-user account screens
- [Organizations](/docs/concepts/organizations) — organization context and membership
- [Authorization](/docs/concepts/authorization) — server-side access decisions
- [Security](/docs/security) — environment signing keys and token handling