Authentication

Issue an API key, send it on either supported header, and understand the three-layer gate behind the 403 that most first calls hit.

Requires API access to be enabled for your workspace

Every v1 request is authenticated with a workspace API key. There are no user tokens and no OAuth: a key is scoped to one workspace and reads only that workspace's data.

Issue a key

In the dashboard, open Settings → API keys and create one. You can give it a name to keep track of where it is used.

The key is shown once, at creation. Only a hash and a short prefix are stored, so it cannot be retrieved later — copy it into your secret store immediately. Lost a key? Revoke it and issue a new one.

Keys look like this:

blm_<random token>

Issuing a key is recorded in your audit log, with the public prefix only — never the key itself.

Send it

Two headers are accepted; use either.

list-chatbots.sh

curl https://app.evoriqa.com/api/v1/chatbots \
  -H "Authorization: Bearer $EVORIQA_API_KEY"

# or
curl https://app.evoriqa.com/api/v1/chatbots \
  -H "x-api-key: $EVORIQA_API_KEY"

list-chatbots.mjs

const res = await fetch("https://app.evoriqa.com/api/v1/chatbots", {
  headers: { Authorization: `Bearer ${process.env.EVORIQA_API_KEY}` },
});
const { data } = await res.json();
console.log(data.data);

list_chatbots.py

import os, requests

res = requests.get(
    "https://app.evoriqa.com/api/v1/chatbots",
    headers={"Authorization": f"Bearer {os.environ['EVORIQA_API_KEY']}"},
    timeout=30,
)
print(res.json()["data"]["data"])

Never hard-code a key, commit one, or ship one to a browser. A key grants read access to the whole workspace. Every sample here reads it from an environment variable — do the same.

A request with no key at all is 401:

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Missing API key." }
}

A key that does not exist, is malformed, or has been revoked is also 401, with "Invalid API key.".

The three-layer availability gate

A valid key is not enough. Access is granted only when all three of these are on:

1
The platform master switch — off by default, controlled by the platform
operator.
2
The per-organisation toggle — on by default, controlled by the platform
operator.
3
The per-plan or per-client entitlement — your plan's API flag, or a
reseller's per-client override of it.

Any one being off returns the same 403, byte for byte:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not enabled for this workspace."
  }
}

Because the message is identical in all cases, retrying tells you nothing — check the switches instead. A resold client should ask their provider; see Per-client API access.

A workspace whose owner account is suspended or deleted receives that same 403, deliberately identical so a key holder cannot distinguish a moderation action from an entitlement gap. The key row itself is untouched and works again as soon as the account is restored.

Nothing about the gate is cached, so flipping any layer takes effect immediately on keys that already exist.

Revoke a key

Settings → API keys → Revoke. Revocation is immediate; the next request with that key is 401. Revoking an unknown or already-revoked key returns 404 rather than reporting a false success.

Rotate by issuing the new key, deploying it, then revoking the old one.

Where to go next

Last updated 8 August 2026