Authentication
Create an API key and use it to call the public REST API.
Every endpoint under /api/v1/ requires an API key, sent as a bearer credential. A missing, invalid, revoked, or expired key gets a 401 problem document with the code unauthorized. See Errors and rate limits for the error format and the request limits that apply to every key.
Create a key
Who can create or revoke keys
Creating or revoking a key requires the API keys: Edit permission. The built-in Admin role has it, and you can grant it to any custom role. Viewing the key list only needs API keys: View (Edit includes it), so someone with view-only access sees each key but no New key or Revoke control. Those controls are hidden without the edit permission, and the action is re-checked on the server, so it still fails with a permission error if called directly.
Click your avatar at the bottom of the dashboard sidebar to open the user menu, choose Organization Settings, then API keys (/dashboard/settings/api-keys).
Give the key a name that says what it's for, for example "Production integration". Optionally set an Expiration (Never, the default, or a preset: in 7, 30, 60, or 90 days, or in 1 year), then click Create key.
Copy the value from the dialog that appears. This is the only time it's shown: the dashboard never displays it again, only an obfuscated version in the key list afterward.
Store it now, or you'll have to create a new one
If you close the dialog without copying the key, there's no way to recover the value. Create a new key instead.
A key is scoped to your organization and grants full access to its data: every site, agent, version, and conversation. Treat it like a password: keep it out of client-side code and version control. Unless you set an expiration when creating it, a key doesn't expire on its own, so revoke it once you no longer need it. An expired key stops working the same way a revoked one does: every request with it gets a 401 (unauthorized). Expiration is set at creation only; to change it, create a new key.
Call the API
Send the key as a bearer token in the Authorization header. Resources other than sites are nested under a site's id. Get one from List sites first:
curl https://www.iadvize.ninja/api/v1/sites/YOUR_SITE_ID/agents \
-H "Authorization: Bearer YOUR_API_KEY"Each key is limited in how many requests it can send per minute, and so is each client address. Over a limit you get a 429 with a Retry-After header: wait that many seconds before retrying. See Errors and rate limits.
See the API reference for the available endpoints.
Revoke a key
Who can revoke keys
Revoking a key requires the same API keys: Edit permission as creating one. The Revoke button is hidden without it, and the action is re-checked on the server, so it fails with a permission error if called directly.
In the API keys table, open the ⋯ menu on the key's row, click Revoke, and confirm. This permanently deletes it (it can't be undone or reactivated) and takes effect immediately: every request is validated directly against WorkOS, with no caching, so the very next call with that key gets a 401.
There's no way to view or copy an existing key's value again. Revoking and creating a new one is the only path if a key is lost.