Getting started / Authentication
Getting started

Authentication

Authenticate Detectivision API requests with an API key in the Api-Key header, over HTTPS. The status endpoints are the only ones that need no key.

On this page

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/json

The 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.