Widgets

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. 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:

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 — authentication UI mounted in your application
• Account Portal — hosted end-user account screens
• Organizations — organization context and membership
• Authorization — server-side access decisions
• Security — environment signing keys and token handling