Products & Surfaces

Client tokens and domain restrictions

Chat widgets use client tokens for authentication and support domain restrictions to prevent unauthorized use.

How client tokens work

When you embed a chat widget, it uses a client token to authenticate with Runtype. Client tokens are:

  • Public — Safe to expose in client-side code
  • Scoped — Limited to a specific Product and surface
  • Domain-restricted — Only work on approved domains

You never manually handle client tokens—the widget script includes them automatically.

Setting up domain restrictions

Configure which domains can use your chat widget:

  1. Open your chat Surface
  2. Go to the Auth tab
  3. Find Allowed Origins
  4. Add origins. Each entry is a full origin including the scheme:

https://example.com https://www.example.com https://app.example.com

5. Click **Save**
The widget will only function on listed origins. Requests from other origins are rejected.
## Wildcard domains
Use wildcards for subdomains:
```plaintext
https://*.example.com

This allows https://app.example.com, https://staging.example.com, and any other subdomain. A *. wildcard matches subdomains only, not the bare apex — list https://example.com separately if you also need the apex.

Using * alone allows any origin. Only use this for testing, never in production.

Development and testing

Add local development origins for testing:

http://localhost:3000
http://127.0.0.1:8080
https://*.ngrok.io

This lets you test the widget locally before deploying.

Multiple environments

Development and production surfaces have separate domain lists:

  • Development surface: Add staging and local URLs
  • Production surface: Add only live domain(s)

This prevents accidentally using production widgets on development sites.

Surface environment also controls which client tokens a surface accepts. Development surfaces accept test client tokens (ct_test_ prefix) only; a live client token (ct_live_ prefix) is rejected by a development surface with an authentication error. New client tokens are created in live mode by default, so this is a common first error when testing a widget on a development surface. Create a test client token for development surfaces, or promote the surface to production to use live tokens.

Protocol and port handling

Origins are matched as full origins, so both protocol and port matter:

  • Patterns must include the scheme. Use https://example.com, not example.com.
  • Protocol must match. An https://example.com pattern does not authorize http://example.com.
  • Port is part of the origin and must match exactly. http://localhost:3000 does not authorize http://localhost:5173.

Troubleshooting domain issues

Widget shows but doesn’t respond:

  1. Check browser console for authentication errors
  2. Verify current domain is in allowed list
  3. Ensure there are no typos in domain names
  4. Check for www vs non-www mismatches

CORS errors:

If you see CORS-related errors, the domain isn’t approved. Add it to the allowed domains list.

Rotating client tokens

If a client token is compromised:

  1. Open your chat Surface
  2. Go to the Auth tab
  3. Click Rotate Token
  4. Confirm the action
  5. Update your widget embed code with the new token

Old tokens stop working immediately after rotation.

Client tokens are different from API keys. API keys are secret and used server-side. Client tokens are public and used client-side with domain restrictions for security.

Next steps