Widget API Keys

Widget API keys connect the Appilot embeddable widget on your web applications to your organization. A key is a public identifier, like a Stripe publishable key: it ships in your page's HTML and is meant to be visible. It is not a password, so the protections below (not secrecy) are what keep it safe to use in the open.

Overview

To embed the Appilot widget on a website, you need a key. The key:

• Acts as a provisioning token for the integration, and is the unit you can rate-limit and revoke
• Restricts usage to allowed domains (a soft check that stops casual copy-paste of your key onto another site)
• Comes in Live or Test variants for different environments

What it does not do, and what protects you instead:

• It is not a secret. Anyone viewing your page can read it. That is expected.
• It does not decide which organization answers on a live site: on a registered production domain, the domain itself determines your organization. The key matters most in development (where there is no registered domain) and for server-to-server use.
• It does not authorize usage on its own. Every conversation is attributed to an identified user (via federation, the built-in login, or SSO); there is no anonymous usage and no opt-out. The key identifies the embed, not the person.
• A key can only read your public knowledge base, never private content.

Creating a key

1. Navigate to Widget Keys in the Backoffice sidebar
2. Click Create Key
3. Fill in the details:

Field	Description
Name	A descriptive label (e.g., "Production - Main Site", "Staging")
Type	Live or Test
Allowed Domains	Comma-separated list of domains where this key is valid
Rate Limit	Maximum requests per minute (optional)

4. Click Create
5. Copy BOTH the public key and the server secret immediately (each is shown once)

Each key has two parts:

• A public key (wk_live_... / wk_test_...) that goes in your page's HTML. Public by design.
• A server secret (wsk_secret_...) that stays on your backend. It is what lets your backend tell Appilot who a user is via the widget token API (see Widget Installation → Connecting your users). Treat it like a password.

warning

The public key value and the server secret are only shown once at creation time (only hashes are stored afterward). Copy them then. Lost the secret? Open the key and Regenerate secret (the public key stays the same, so your embeds keep working). Lost the public key? Create a new key.

Live vs Test keys

Feature	Live Key	Test Key
Purpose	Production websites	Development and localhost
Domain enforcement	Soft check against allowed domains	None (works on localhost and unlisted domains)
Where it works	Production backend only	Development only, rejected by the production backend
Rate limits	Enforced	Enforced (can be set higher for testing)
Analytics	Included in production analytics	Excluded from production analytics
Billing	Token usage counts toward billing	Token usage may be excluded (check your plan)

tip

Use a Test key during development (it is the easiest way to point a localhost page at your organization, since there is no registered domain locally) and a Live key in production. A Test key is intentionally rejected by the production backend, so it cannot leak into a live site.

Managing keys

The Widget Keys page lists all your organization's API keys:

Column	Description
Name	The key's label
Type	Live or Test
Allowed Domains	Domains where the key is authorized
Created	When the key was created
Last Used	When the key was last used in a request
Status	Active or Revoked

Allowed domains

Allowed domains control where the widget can operate with a given key. The backend checks the Origin or Referer header of incoming requests against the allowed domain list.

Domain format

• Use bare domains without protocol: example.com, app.example.com
• Subdomains must be listed explicitly: example.com does not cover app.example.com
• Wildcards are not supported, list each domain individually

Updating domains

1. Click on the key you want to modify
2. Edit the Allowed Domains field
3. Save your changes

Changes take effect immediately: new requests are validated against the updated list.

Widget sign-in (built-in login)

The Widget Keys page also holds one organization-wide setting: Widget sign-in.

Every widget conversation belongs to an identified user; there is no anonymous usage. Most sites identify their users automatically (your developers pass a federation token when embedding the widget), and those visitors never see any sign-in screen. This switch decides what happens to visitors that arrive without an identity:

• On: the widget shows Appilot's built-in sign-in / register form, so the visitor can identify themselves and use the assistant. The account must be a member of your organization.
• Off (default): the widget shows a "Sign in to continue" notice and the assistant stays locked for that visitor.

Turn it on when your site has no user accounts of its own, or when your users already have Appilot accounts (internal tools, member portals). Leave it off when your developers federate identity from your own app: the form would only confuse visitors who should be identified automatically.

Only organization admins can change this setting. Developers can also enable the form per embed with the data-user-auth="true" attribute; either switch is sufficient.

Revoking a key

If a key is compromised or no longer needed:

1. Find the key in the list
2. Click Revoke
3. Confirm the action

note

Revoking a key is immediate and permanent. Any website using that key will lose widget functionality instantly. Make sure you have a replacement key deployed before revoking.

Security best practices

A widget key is public by design, so "keep it secret" does not apply. The practices that do matter:

• Use separate keys for each environment (development, staging, production)
• Restrict allowed domains to only the sites that need the widget, so a copied key is rejected by other sites' browsers
• Set rate limits to bound usage if a key is abused
• Rotate keys periodically: create a new key, deploy it, then revoke the old one
• Monitor "Last Used": if a key has not been used in months, consider revoking it
• You may commit the public key (it ships in your public HTML anyway). The server secret is different: keep it out of source control and out of the browser, like any backend password, in an environment variable or secret manager

Next steps

• Billing & Payments: View subscription and payment details
• Domain Configuration: Configure domains for the knowledge base