Products & Surfaces

Client tokens and domain restrictions

Use a client token to authenticate a chat widget in client-side code. The token is public, scopes requests to its capabilities, and restricts requests by origin.

How client tokens work

The generated widget embed code includes the client token that you select on the Ship tab. Client tokens have these properties:

  • Public: Include a client token in client-side code. Keep API keys in server-side code.
  • Capability-scoped: The token authorizes calls only to the Flows and Agents that you attach to it.
  • Origin-restricted: The token accepts requests when the request origin matches its allowedOrigins list. Test tokens also allow local origins automatically.

Create a client token

Link at least one Flow or Agent to the chat Surface before you create a token. The API rejects a token without a linked capability.

To create a client token, follow these steps:

  1. In the Runtype dashboard, open your Product and select the chat Surface.
  2. On the Surface panel, click Auth.
  3. In the Client Tokens section, click Create Token.
  4. Enter a name for the token.
  5. In the Allowed Origins field, enter a comma-separated list of origins.
  6. Click Create Token. The token appears in the token list.

Copy the token from its row. On the Ship tab, select the token to generate the widget embed code.

Set allowed origins

Set the token’s allowedOrigins value to the origins that can use the widget. In the dashboard, enter a comma-separated list in Allowed Origins when you create the token. Enter the scheme and hostname, and include the port when the site uses a non-default port.

Use these origin forms:

  • https://example.com: an exact origin.
  • https://www.example.com: a hostname that differs from example.com.
  • http://localhost:3000: a local origin with port 3000.

Do not enter a bare hostname such as example.com. The scheme must match the request origin.

Allow subdomains

To match subdomains under one hostname, enter https://*.example.com in Allowed Origins.

Runtype matches https://app.example.com and https://staging.example.com, but it does not match https://example.com. Add https://example.com separately when you need the apex domain.

To allow every origin, enter *. Avoid this setting on a Surface that serves live traffic because it removes origin filtering.

For a native app that sends no Origin header, enter native as an allowed origin. This entry admits originless requests and does not match a web origin. Use a separate token for native apps because this setting removes origin protection for that token.

Choose a token environment

A client token is a test token or a live token. Every Surface accepts both:

  • Test token (ct_test_ prefix): revealable after creation, with a daily execution cap. Use it while you build.
  • Live token (ct_live_ prefix): shown once, with no execution cap. Use it for real traffic.

The dashboard creates live tokens by default. To create a test token, use the Client Tokens API reference and set environment to test.

Test client tokens automatically allow http://localhost, http://127.0.0.1, http://0.0.0.0, and http://[::1] with any port. Add staging and tunnel origins to Allowed Origins explicitly.

Target a version or release alias

By default a client token runs the agent’s live saved configuration, exactly as before. A token can instead be aimed at a specific agent version through the Client Tokens API or the create_client_token / update_client_token MCP tools. This is not in the dashboard yet.

A token carries at most one of these, never both:

  • targetAlias — a release alias the token follows. It is re-resolved on every request, so deploying a new version at that alias changes what the token runs without touching the token.
  • targetVersionId — one immutable agent version. It is never re-resolved, so the token keeps running that exact configuration until you change it.

Rules to know before you set one:

  • targetVersionId requires the token to carry exactly one agent id, and that version must belong to that agent.
  • targetAlias requires an organization-scoped token. A personal-account token cannot follow an alias.
  • An alias that names nothing returns a 404 identifying the pointer. It never falls back to the live configuration.
  • Targeting is not available for external or Claude Managed agents, which return 422.
  • Realtime voice always runs the live configuration and returns 422 for a targeted token.
  • A chat request that supplies its own agent.alias or agent.versionId must exactly restate the token’s target, or the request is rejected with 400. A token with no target accepts no selector at all.

pinToVersion is a separate legacy field that selects a widget version mode (latest or published). It has never selected an agent version and still does not: a value shaped like an agent version id stored there is inert and the token keeps running live. Set targetVersionId to pin a version.

Check exact origin matching

For exact origin entries, Runtype compares the scheme, hostname, and port. Check these values when a request fails:

  • Scheme: https://example.com does not match http://example.com.
  • Hostname: example.com does not match www.example.com.
  • Port: http://localhost:3000 does not match http://localhost:5173.

Requests from an unmatched origin receive 403 with an Origin not allowed error.

Wildcard subdomain entries match the protocol and subdomain hostname. Use exact origins when port-specific matching matters.

Update permissions on existing sessions

Runtype rechecks the token’s current allowed origins on session requests. Chat messages and tool-result resumes also recheck that the session’s Flow or Agent remains attached to the token. Removing a target or origin stops affected existing conversations before another execution. Creating a new session does not restore the removed permission.

Keep the native entry when an integration intentionally sends no Origin header. Test tokens retain their automatic local-origin allowance. If a permission was removed by mistake, correct the token configuration before retrying.

Troubleshoot rejected requests

Use these checks when the widget loads but does not respond:

  1. Check the browser console for an origin or CORS error.
  2. Compare the page origin with the token’s Allowed Origins values.
  3. Confirm that the Surface is active and has at least one enabled Flow or Agent.

Regenerate a client token

If someone exposes a client token, regenerate it with the client token API. Regeneration preserves the token’s capabilities, allowed origins, and environment while issuing a new token value.

After regeneration, the previous token becomes invalid immediately. Update the widget embed code with the regenerated token.

Next steps