Authentication

Send your secret key as a bearer token in the Authorization header of every request:

Authorization: Bearer aide_sk_live_...

Requests without a valid key get 401, with the header WWW-Authenticate: Bearer. Requests over plain http:// are refused, not redirected, so a misconfigured client fails at once instead of sending its key unencrypted on every call. A key that was ever sent over http:// must be treated as exposed.

Getting and rotating keys

• We issue keys during onboarding and deliver each one through a one-time secure link.
• We store only a hash of each key. We cannot show a key again; if you lose one, we issue a new one.
• Treat keys as opaque strings: only the prefix is fixed, and the length can change.
• You can hold several active keys per mode, for example one per server.
• To rotate without downtime, ask us for a new key, deploy it, then revoke the old one.

Revoking a key

If a key may have been exposed, revoke it yourself at once. Call this endpoint with the key you want to revoke:

POST /v1/api_key/revoke

The key stops working immediately, and the response is 200 with { "object": "api_key", "revoked": true }. Then tell us, and we will issue a replacement.

Restricted keys

By default a key can call every endpoint. On request we issue restricted keys limited to the scopes you choose, for example a read-only key for a reporting service. A restricted key that calls an endpoint outside its scopes gets 403 insufficient_scope.

Scope	Endpoints
papers:read	GET /v1/subjects, GET /v1/papers, GET /v1/papers/{id}, GET /v1/papers/{id}/questions, GET /v1/files/{id}
papers:write	POST /v1/files, POST /v1/papers, PATCH /v1/papers/{id}, DELETE /v1/papers/{id}, POST /v1/papers/{id}/approve, POST /v1/papers/{id}/review_links, POST /v1/papers/{id}/review_links/revoke
submissions:read	GET /v1/submissions, GET /v1/submissions/{id}, GET /v1/submissions/{id}/result, GET /v1/submissions/{id}/report, GET /v1/files/{id}
submissions:write	POST /v1/files, POST /v1/submissions, PATCH /v1/submissions/{id}, POST /v1/submissions/{id}/cancel, POST /v1/submissions/{id}/release, DELETE /v1/submissions/{id}
billing:read	GET /v1/account, GET /v1/balance, GET /v1/credit_transactions
webhooks:manage	Every /v1/webhook_endpoints endpoint
events:read	GET /v1/events, GET /v1/events/{id}

Every key, restricted or not, can revoke itself.

IP allowlisting

On request we limit a key to the IP addresses or ranges you give us. A request from anywhere else gets 403 ip_not_allowed.

Keeping keys safe

• Use keys only on your servers. Never put them in a browser, a mobile app, a URL or source control.
• Store them in a secrets manager or encrypted environment variables, and keep them out of logs.
• Treat a key as exposed if it was ever sent over http://, pasted into a chat or ticket, or committed anywhere. Revoke it.