Authentication
Use a personal API key for your server-side integration and keep it separate from the business records you submit.
Create and store a key
- Sign in to your account using the one-time email code.
- Create a named API key for the integration you are setting up.
- Copy the full key when it is shown and store it in your deployment’s secret store or server-side environment.
Keys use the form oa_live.<id>.<secret>. The full secret is shown once. The account page is also where you revoke a key; do not include it in browser JavaScript, source control or shared request examples.
Send the authorization header
Every authenticated API request sends Authorization: Bearer <key>. In these examples, OPENAUDITOR_API_KEY is an environment variable containing your key.
curl "https://openauditor.ai/api/v1/configuration" \
-H "Authorization: Bearer $OPENAUDITOR_API_KEY"A successful configuration read returns 200. It includes engine_version, model, the default_certainty_target and the configuration and question qualifications for each registered use case. A running model can have unqualified questions; a loaded model does not by itself authorize its answers to decide checks.
Public reads and authenticated work
| Access | Routes |
|---|---|
| Public | /v1/use-cases, use-case detail, /v1/evals, the OpenAPI document and health. |
| API key | /v1/configuration, /v1/usage, single verification, audit creation, audit results, review marks and audit deletion. |
The built-in console uses your signed-in session for same-origin requests. An external integration uses an API key. Audit access is scoped to the owning account: knowing an audit ID does not grant access to its inputs or results.
Rotate credentials without losing the integration
Create a replacement key, update the application’s secret, and verify that the application can read its configuration. Revoke the old key after the replacement works. Account quotas are shared across keys, so making another key does not create a separate quota.
A Free account supports up to five active API keys; a paid plan may allow more. Keys expire after 365 days, and the account’s email gets one notice 14 days before; they can be revoked sooner. Review the account page for the keys your applications still need.
Give dashboards a read-only key
Tick Read-only when you create a key for a dashboard, report or monitoring job. It can read audits, results, sources and usage with GET and HEAD requests. Any other request, such as a verification, an audit submission or a deletion, is refused with 403 read_only_key before it counts toward your rate limit.
Check your plan and allowance
Every plan includes the API. An integration can read its account’s plan, limits, today’s usage and what remains before the 00:00 UTC reset:
curl "https://openauditor.ai/api/v1/usage" \
-H "Authorization: Bearer $OPENAUDITOR_API_KEY"The Worker answers this from your account’s own record. It counts as one request toward the per-minute limit, adds no item or question usage, and still answers after a daily quota is spent. remaining shows how much is left before new verifications and audits are refused; it does not reserve capacity for a submission.
If authentication fails
| Response | What to check |
|---|---|
401 missing_api_key | The Authorization header is absent. Supply the Bearer header on the authenticated request. |
401 invalid_api_key | Check the complete key and Bearer syntax. The key may be expired or revoked. |
401 session_required | The built-in console session ended; sign in again. This is distinct from API-key authentication. |
429 | The request reached a rate or usage limit. Inspect the specific error and Retry-After; repeatedly replacing the key will not resolve a shared quota. |
Keep Request-Id when reporting a failed request. Remove the key and private business data from diagnostic material.
Continue reading
- Verify an item — make the first authenticated verification request.
- Security — understand credential and request handling.
- Error guide — read the response format and recovery paths.