Every request to the API carries an API key in the Api-Key header:
POST /api/v1/moderation HTTP/1.1
Host: api.detectivision.ai
Api-Key: 3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c0d
Content-Type: application/jsonThe status endpoints are the only ones that need no key.
Note
Use the Api-Key header, not Authorization: Bearer. The API is called over HTTPS only.
API keys#
Create and manage keys in Dashboard → API Keys. A key is a 36-character identifier such as 3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c0d.
- The full key is shown once, when it is created. Store it then; afterwards the dashboard shows only its first and last four characters.
- A key belongs to your account. Requests with any of your keys use your account's credits and appear in your moderation history.
- Deleting a key stops it at once.
- Use a separate key per application or environment, so you can rotate or revoke one without touching the others.
Permissions#
Each key has a permission:
| Permission | Can do |
|---|---|
read |
Only GET endpoints, such as reading a request back or listing your flags. Cannot run checks. |
write |
Everything: run checks, take actions, start and stop live sessions, and read. |
readwrite |
Same as write. |
restricted |
Nothing. Every request is refused. Use it to pause a key without deleting it. |
A read key on a POST or DELETE endpoint gets 403 forbidden: This API key does not have write permission.
Expiry#
A key can have an expiry date. After it, requests get 401 unauthorized: This API key has expired. Change or remove the expiry in the dashboard at any time.
Errors#
| HTTP | error |
message |
Meaning |
|---|---|---|---|
| 401 | unauthorized |
An API key is required: send it in the Api-Key header. |
No Api-Key header. |
| 401 | unauthorized |
The API key is not valid. |
Unknown or deleted key. |
| 401 | unauthorized |
This API key has expired |
The key's expiry date has passed. |
| 401 | unauthorized |
Account is not active |
The account the key belongs to is not active. |
| 403 | forbidden |
This API key is restricted |
The key's permission is restricted. |
| 403 | forbidden |
This API key does not have write permission |
A read key on a POST or DELETE endpoint. |
Keeping keys safe#
- Call the API from your server. Browsers cannot call it directly (cross-origin requests are refused), which also keeps the key out of your pages.
- Keep keys in environment variables or a secrets manager, never in source control.
- If a key leaks, delete it in the dashboard and create a new one.