apiKeys.revoke
Revoke an API key.
Permanently revokes an API key. Where finished keys are retained for 180 days (see List API keys), an id in the form keys are minted in (26 upper-case Crockford base32 characters) that no principal holds unrevoked, such as a key already revoked or one the retention removed, answers 200 without changing anything; a key another principal still holds, or an id in any other form, answers 404. A system key the deployment's SYSTEM_KEYS secret serves (listed by its id, or by its stored hash under any id) authenticates from the secret, not from its row, so revoking it here is refused (409 system_key_in_secret) until the entry is removed from the secret; while SYSTEM_KEYS is set but does not parse, revoking any system key is refused (409 system_keys_invalid), since fixing the secret could bring a revoked key back.
openemail.apiKeys.revoke(
apiKeyId: string,
options?: CallOptions,
): ApiPromise<RevokedResult>It calls DELETE /api-keys/{apiKeyId}: Revoke an API key in the API reference.
Example
const revokedResult = await openemail.apiKeys.revoke(apiKeyId)Arguments
| Argument | Type | Description |
|---|---|---|
apiKeyId | string | API key ULID identifier. The path's {apiKeyId}. |
Options
It takes no options of its own. Every call also takes signal, timeout, retry and headers, which say how that one call is sent (call options).
Answer
Awaited, it is the API's JSON, RevokedResult. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.
Errors
| Status | What it means |
|---|---|
401 | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge |
404 | API key not found or not accessible to this principal |
409 | System callers only. system_key_in_secret: the SYSTEM_KEYS secret serves the key and it keeps authenticating from it (listedAs names the entry); remove that entry from the secret and deploy, then revoke. system_keys_invalid: SYSTEM_KEYS is set but does not parse, and fixing it could bring a revoked system key back; fix it (or clear it) and deploy, then revoke |
503 | temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description) |
A failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.
Types
It names these types of the API, each on a page of its own: RevokedResult.