API keys

Create and revoke personal API keys, and issue Coworker and App keys from the company-wide list.

For: Everyone for personal keys; administrators for Coworker and App keys · Last updated

An API key lets a program authenticate without a person signing in. Every key starts with wi_sk_. A key is bound to one owner: a person, a Coworker or an App. Calls to a Coworker's webhook trigger URL accept personal keys only.

Who can manage which keys#

Key bound to Who can create, list and revoke it
A person (personal key) That person. An administrator can also manage them.
An App The App's Builder, anyone with the manage_apps ability, or an administrator.
A Coworker Administrators only (the admin ability).

Personal keys#

Every signed-in person manages their own keys on Settings, under My API Keys. People with the admin ability find it on the Personal tab; everyone else sees it as soon as the page opens. These keys are "bound to your own account and can be used to call the platform's API on your behalf." For example, a personal key authorizes calls to a Coworker's webhook trigger URL, sent as an Authorization: Bearer wi_sk_... header; the key's owner must be allowed to chat with that Coworker.

  1. Select New key.
  2. Optionally enter a Label (optional) describing what the key is for. Without a label the list shows a masked form of the key.
  3. Optionally enter a Monthly budget, $ (optional). Leaving it blank sets no limit.
  4. Select Create key.

The page then shows Your new API key with the full key and the warning "This is the only time this key will be shown. Copy it now — it cannot be retrieved again." Select Copy, store the key somewhere safe, and select Done. After that the key cannot be displayed again.

The list shows Label, Created, Last used and Status for each key. To revoke one, select Revoke on its row and confirm "Revoke this key?" ("Anything using it will stop working immediately.") with Revoke key. Revoked keys are hidden; select Show revoked (n) to list them.

Company-wide Coworker and App keys#

Administrators manage keys bound to Coworkers and Apps at Settings → Administration → API Keys · coworkers & apps → Manage. People without the admin ability see "Managing Coworker API keys requires the admin role."

The list shows every Coworker and App key in the company, with Principal (the kind of owner and its ID), Label, Budget ("unlimited" when none is set), Created, Last used and Status. It does not list personal keys.

To create a key:

  1. Select New key.
  2. Under Bind to, choose A Coworker or An App, then pick the Coworker or App.
  3. Optionally set Label (optional) and Monthly budget, $ (optional).
  4. Select Create key, then copy the key from Your new API key before you select Done.

Select Revoke on a row to revoke a key, as above. Revoking takes effect immediately.

Keys on an App's page#

A Builder, anyone with manage_apps, or an administrator can also issue and rotate an App's key from the App's own page, in the API Key panel. Issue API key creates the first key. Rotate key… asks "Rotate this App's API key?" ("The current key stops working immediately. Anything already deployed with it will need the new one.") and replaces the active key with a new one that is shown once.

Handling keys safely#

  • Treat a key like a password. Anyone holding it can act as its owner.
  • The full key is shown only once, at creation. Only a hash is stored. If a key is lost, revoke it and create another.
  • Revoke the keys of a person who leaves. Revoking the person blocks their personal keys from authenticating.