Revoke an API key
Request, parameters, response and errors of DELETE /v1/apiKeys/{id}.
Last updated:
Revokes the key: its next call answers 401 and nothing brings it back. The key may be the calling key. The office history shows it like a revocation in the app, with the calling key (name and id) as the actor. Revoking a key that is already revoked changes nothing and answers the same. Limited to 5 in a burst and then one every 20 seconds per key, like the app. Needs write access to apiKeys; only a key that the management of the office created can have it.
Requires the scope propose.
Request
DELETE https://api.athaus.ai/v1/apiKeys/{id}Parameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | UUID of the key. |
Header
| Name | Type | Required | Description |
|---|---|---|---|
Athaus-Version | string | no | Optional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported. |
If-Match | string | no | Only if the current ETag of the resource is listed (or *: only if the resource exists). Otherwise 412 and nothing is written. |
Example
curl -X DELETE "https://api.athaus.ai/v1/apiKeys/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17" \
-H "Authorization: Bearer ath_live_..."Response
On success the status is 200 with ApiKey.
ApiKey
| Field | Type | Description |
|---|---|---|
object | string | Always api_key. |
id | string (uuid) | |
name | string | null | |
prefix | string | The first characters of the key, enough to recognise it. Never the key. |
mode | string | One of live, test. |
scopes | string[] | What the key may do: read, propose, approve, and decide where the key may say yes or no to a proposal. One of read, propose, approve, decide. |
permissions | object | What the key may do per resource: none, read, write. |
permissions.listings | string | One of none, read, write. |
permissions.contacts | string | One of none, read, write. |
permissions.inquiries | string | One of none, read, write. |
permissions.viewings | string | One of none, read, write. |
permissions.files | string | One of none, read, write. |
permissions.webhookEndpoints | string | One of none, read, write. |
permissions.apiKeys | string | One of none, read, write. |
permissions.projects | string | One of none, read, write. |
current | boolean | true for the key that made this request. |
createdAt | string (date-time) | |
lastUsedAt | string (date-time) | null | At most hourly exact. Null if it was never used. |
revokedAt | string (date-time) | null | When the key was revoked. A revoked key answers 401 and stays listed for a year. Null while it works. |
Response headers
| Header | Description |
|---|---|
Request-Id | Identifies this request. Quote it in a support request. |
Athaus-Version | The API version of this response: v1. |
Athaus-Release | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Errors
Every error arrives as problem details. Branch on code, not on title or detail.
| Status | Codes | Meaning |
|---|---|---|
400 | invalid_id, api_version_unsupported, invalid_input | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. | |
412 | precondition_failed | The condition of If-Match (or If-None-Match) does not hold for the current state of the resource. Nothing was written. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.