Authentication
Authenticate requests with Bearer API keys
All API requests require a valid API key passed as a Bearer token.
Making authenticated requests#
Include your API key in the Authorization header:
curl https://api.omnifence.ai/api/v1/job/YOUR_JOB_ID \
-H "Authorization: Bearer YOUR_API_KEY"
Obtaining API keys#
Create and manage API keys from the API Keys page in the Omnifence dashboard. The full key value is shown once at creation. Copy it and store it securely. The dashboard shows only the prefix afterwards.
Each key is owned by your account and inherits your organization's rate limits and scopes.
Treat API keys as secrets. Do not commit them to version control or expose them in client-side code. If a key leaks, revoke it from the dashboard and create a new one.
If the key is invalid, disabled, or missing, the API returns a 401 UNAUTHORIZED error.
Scopes#
Each API key carries one or more scopes. The API enforces scopes at runtime. A request that is missing the required scope receives a 403 FORBIDDEN response.
| Scope | Required for |
|---|---|
moderate:text |
POST /api/v1/moderate/text |
moderate:image |
POST /api/v1/moderate/image |
moderate:video |
POST /api/v1/moderate/video |
moderate:audio |
POST /api/v1/moderate/audio |
job:read |
GET /api/v1/job/{id} |
webhook:manage |
/api/v1/webhook/register, /api/v1/me/webhook-secrets/* |
account:config |
PUT /api/v1/me/moderation-config, /api/v1/me/custom-categories/* (writes) |
registry:check |
POST /api/v1/registry/check |
registry:submit |
POST /api/v1/registry/entries, GET /api/v1/registry/entries, POST /api/v1/registry/entries/{id}/revoke |
A key you create carries every scope in the table above except webhook:manage,
account:config and the two registry:* scopes, so it can submit any modality and read any job. Usage and billing are viewed and
managed in the dashboard, not via the API.
webhook:manage registers the callback URL and reads and rotates your
webhook signing secret. The URL decides who receives every
verdict, and the secret is what proves a callback came from us, so a key holding this scope can
redirect or forge deliveries, and rotating with it breaks a receiver that has not redeployed yet.
account:config changes what the pipeline rejects for every future job: the per-category toggles and
your custom categories. A key that only submits content must not be able to switch coverage off, so
this scope is also off by default.
Both are session scopes: manage the callback URL, the signing secret and moderation configuration from the dashboard under Account, where your session carries them. Reading the current configuration and custom categories needs no extra scope.
If your key is missing a required scope, the API returns 403 FORBIDDEN. Contact support if you
need the scopes on your key adjusted, including webhook:manage or account:config.
Shared Registry keys#
registry:check and registry:submit come only on a registry key, which Omnifence issues when your
Shared Registry membership becomes active. A registry key carries no other
scope, so it cannot submit moderation jobs, and a moderation key cannot call the registry. You cannot
create a registry key from the dashboard.
Account termination#
If your account has been terminated (for example, after a manual review following repeated policy violations), all requests return a 403 ACCOUNT_TERMINATED error regardless of the API key used.
{
"error": "ACCOUNT_TERMINATED",
"message": "Account has been terminated",
"statusCode": 403
}