API Keys
How agents authenticate with Vigilator - creating, using and revoking organisation API keys.
Agents talk to Vigilator with an API key. Keys belong to an organisation rather than a person: a request made with a key acts for that organisation - opening interrupts into its inbox, starting sessions in its Live View - and can never touch another organisation's data. There is no limit on how many keys an organisation can have, so give each agent, environment or deployment its own.
Creating a key
Open the Api Keys tab
In the dashboard, go to your organisation's Integrations page. The Api Keys tab is the first one. You need the apiKey.create permission - held by owners and the built-in Developer role.
Create key
Press Create key and give it a name (up to 32 characters - name it after what will use it, such as Production agent or Staging - billing bot) and an expiry: Never, 7 days, 30 days or 90 days. The expiry can't be changed later, so pick it at creation.
Copy it now
The full key is shown once, straight after creation. Copy it into your secret store before pressing Done - only its first few characters are kept, and it cannot be recovered afterwards. If you lose it, revoke it and create another.
Keys look like vgl_ followed by 64 letters. The table on the tab lists each key's name, its first characters, when it was created, when it expires, and when it was last used, so you can spot keys that are no longer in use.
Using a key
Send the key in the x-api-key header of every request:
curl -X POST https://vigilator.ai/api/interrupts \
-H "Content-Type: application/json" \
-H "x-api-key: vgl_..." \
-d '{ "title": "Send onboarding email", "actionRequests": [ ... ] }'The Python SDK does this for you - pass the key to Client and it's attached to every call. Authorization: Bearer is not supported; the header is always x-api-key.
Keep it server-side
An API key grants full access to the organisation's machine-facing API. Treat it like a password: never ship it in a browser bundle or a mobile app, and never commit it. If a key leaks, revoke it immediately - anything still using it stops working the moment you do.
What a key can do
A key is authorised for the machine-facing endpoints - the ones an agent needs:
| Endpoint | Purpose |
|---|---|
POST /api/interrupts | Open an interrupt |
GET /api/interrupts/{id} | Read an interrupt, including its decisions |
GET /api/interrupts | List the organisation's interrupts |
POST /api/sessions | Start a Live View session |
POST /api/sessions/{id}/messages | Append messages to a session |
POST /api/sessions/{id}/end | End a session |
Keys carry no role of their own - a valid key can call any of these for its organisation, regardless of who created it. Everything humans do in the dashboard (deciding, assigning, escalating, disconnecting, managing webhooks or billing) is reserved for signed-in members, and a request that tries it with a key is refused with 403 This endpoint is reserved for humans.
The full request and response shapes are in the API reference.
Errors
| Status | Message | Cause |
|---|---|---|
401 | Missing x-api-key header. | The header wasn't sent. |
401 | Invalid API key. | The key doesn't exist, or was revoked. |
401 | API Key has expired | The key passed its expiry. Expired keys are removed from the list automatically. |
403 | This endpoint is reserved for humans. | The endpoint is dashboard-only. |
402 | This organisation has used its included messages for the month… | The organisation's interrupt allowance is spent - see Billing. |
402 | This organisation has used its included agent hours for the month… | The organisation's monitoring allowance is spent. |
Renaming and revoking
Each row's menu offers Rename and Revoke. Revoking deletes the key: anything still authenticating with it fails immediately, and it cannot be undone. Renaming needs apiKey.update, revoking needs apiKey.delete, and seeing the list needs apiKey.read - owners and Developers hold all of them, Managers can view only. Set them on custom roles under access control.
Rotating a key
There's no in-place rotation; rotate by overlap:
- Create a new key.
- Deploy it to the agent.
- Once the old key's Last used column stops moving, revoke it.