Admin API keys

An Admin API key is a long-lived credential for the Admin API. It authenticates as the account that created it, has its own ACL set, and authenticates only requests to paths below /v1/admin.

Every operation on this page requires admin_api_key:manage. A successful operation records one Admin audit entry with target type admin_api_key and the X-Audit-Log-Reason header as its reason. A request that returns an error records no entry. An operation that addresses one key returns 404 ADMIN_API_KEY_NOT_FOUND when any of these holds:

• No key has that identifier.
• Another account created the key.
• The key has expired.

Key management is scoped to the creating account

The wildcard ACL reaches no key created by another account, and such a key reports ADMIN_API_KEY_NOT_FOUND.

Admin API key object

A key is owned by the account that created it, and it stores its own ACL set. Removing an ACL from the owning account and removing an ACL from the key are separate changes.

FiveCord checks both sets when a request presents a key. A request passes when all of these hold:

• The owning account holds admin:authenticate or *.
• The owning account holds the ACL the operation requires, or *.
• The key itself has that ACL, or *.

A key therefore never has wider permission than the account behind it.

Structure

Field	Type	Description
key_id	snowflake	The ID of the key
name	string	The name given to the key (1-100 characters)
acls1	array[string]	The ACLs stored on the key
created_by_user_id2	snowflake	The ID of the account that created the key, and whose identity the key assumes
created_at	ISO8601 timestamp	Time the key was created
last_used_at3	?ISO8601 timestamp	Time the key last authenticated a request, or null when it never has
expires_at4	?ISO8601 timestamp	Time the key expires, or null when the key does not expire

¹ Bounded at the size of the ACL registry. Every value written through this API is a registry member

² Never changes, so a key cannot be transferred to another account

³ Written on every successful authentication, including when the authenticated operation is a read

⁴ An expired key is absent from every listing and is reported as not found

Example

{
  "key_id": "1501314428688998182",
  "name": "moderation-tooling",
  "acls": ["user:lookup", "report:view", "report:resolve"],
  "created_by_user_id": "1489200013322551296",
  "created_at": "2026-05-14T09:12:44.183000+00:00",
  "last_used_at": "2026-06-02T18:40:11.902000+00:00",
  "expires_at": null
}

Admin API key creation object

Only Create Admin API key returns this object. It has the raw credential and omits last_used_at and created_by_user_id.

Structure

Field	Type	Description
key_id	snowflake	The ID of the key
key1	string	The raw credential the key authenticates with
name	string	The name given to the key (1-100 characters)
created_at	ISO8601 timestamp	Time the key was created
expires_at2	?ISO8601 timestamp	Time the key expires, or null when the key does not expire
acls3	array[string]	The ACLs stored on the key

¹ An opaque key, presented as Admin <token> in the Authorization header

² Derived from expires_in_days at the instant the key is created, and null when that field is omitted

³ Reflects the stored set, so a value repeated in the request appears once

The secret is returned once

The secret cannot be retrieved or rotated later. If it is lost, revoke the key and create a replacement.

Example

{
  "key_id": "1501314428688998182",
  "key": "fa_1501314428688998182_7Qk2ZbW9xLmR4TnP0vAeJdCyHs6UgF1B",
  "name": "moderation-tooling",
  "created_at": "2026-05-14T09:12:44.183000+00:00",
  "expires_at": "2026-08-12T09:12:44.183000+00:00",
  "acls": ["user:lookup", "report:view"]
}

List Admin API keys

GET/v1/admin/api-keysAudit reason

Returns every Admin API key object the acting account created, as a bare JSON array with no ordering guarantee. Requires admin_api_key:manage.

A key past its expiry is never returned.

Response

Status	Body	Condition
2001	array[Admin API key object]	Keys were returned

¹ An account that created no key receives an empty array

Side effects

The operation records one Admin audit entry with action list_admin_api_keys, target type admin_api_key, target ID 0, and metadata key result_count.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Create Admin API key

POST/v1/admin/api-keysAudit reason

Creates a key and returns an Admin API key creation object that has the raw credential, with HTTP 200, not 201. Requires admin_api_key:manage.

The acting credential must already have every value in acls, unless it has *. The key authenticates immediately, and its effective permission is the intersection described under Admin API key object.

JSON body

Field	Type	Description
name1	string	The name given to the key (1-100 characters)
expires_in_days?2	integer	The number of days until the key expires (1-365)
acls3	array[string]	The ACLs stored on the key, each a registry value (at most 111)

¹ A value that is empty after trimming is rejected, so whitespace alone is not a name

² The stored expiry is the request instant plus this many days. Omitting the field creates a key that does not expire

³ An empty array produces a key that satisfies no operation. FiveCord compares acls against the presenting key’s own ACLs, so a key cannot issue a broader key

FiveCord rejects the request with 403 MISSING_ACL on the first ungrantable value. A request that names several ungrantable ACLs reports only that one.

Response

Status	Body	Condition
200	Admin API key creation object	Key was created
400	error response	Body validation fails, including an acls value outside the ACL registry, returned as INVALID_FORM_BODY
403	error response	Credential type is refused, admin_api_key:manage is absent, or acls names a value the acting credential does not have

Side effects

The operation records one Admin audit entry with action create_admin_api_key, target type admin_api_key, target ID equal to the new key_id, and metadata keys acls and expires_in_days. acls is the stored ACL set joined with commas. expires_in_days is present only when the request supplied it. The entry has no name and no raw credential.

Rate limit

30 requests per minute for each authenticated user, on the admin:code:generation bucket.

Get Admin API key

GET/v1/admin/api-keys/{key_id}Audit reason

Returns one Admin API key object. Requires admin_api_key:manage.

This operation never returns the raw credential.

Path parameters

Field	Type	Description
key_id	snowflake	The ID of the key

Response

Status	Body	Condition
200	Admin API key object	Key was returned
404	error response	ADMIN_API_KEY_NOT_FOUND, which also covers an expired key and a key created by another account

Side effects

The operation records one Admin audit entry with action get_admin_api_key, target type admin_api_key, target ID equal to key_id, and no metadata.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Update Admin API key

PATCH/v1/admin/api-keys/{key_id}Audit reason

Renames a key or replaces its ACL set, and returns the updated Admin API key object. Requires admin_api_key:manage.

FiveCord leaves an omitted field unchanged, and the supplied fields take effect on the key’s next authenticated request. The acting credential must already have every value in a supplied acls, unless it has *. A key with an expiry keeps it.

Supplying acls replaces the whole stored set

An update never rotates the credential, and no field on this route changes the expiry, so revoking the key is the only way to disable it.

Path parameters

Field	Type	Description
key_id	snowflake	The ID of the key

JSON body

Field	Type	Description
name?1	string	The replacement name for the key (1-100 characters)
acls?2	array[string]	The complete replacement set of ACLs, each a registry value (at most 111)

¹ A value that is empty after trimming is rejected

² An empty array leaves the key with no ACLs, so the key satisfies no operation. An empty request body is accepted and changes nothing

Response

Status	Body	Condition
200	Admin API key object	Key was updated
400	error response	Body validation fails, including an acls value outside the ACL registry, returned as INVALID_FORM_BODY
4031	error response	Credential type is refused, admin_api_key:manage is absent, or acls names a value the acting credential does not have
404	error response	ADMIN_API_KEY_NOT_FOUND, which also covers an expired key and a key created by another account

¹ The ownership check runs before the ACL grant check, so a key belonging to another account returns 404, not 403

Side effects

The operation records one Admin audit entry with action update_admin_api_key, target type admin_api_key, target ID equal to key_id, and metadata keys fields and acls. fields lists the supplied field names joined with commas, and is empty for an empty body. acls is the stored ACL set joined with commas, present only when the request supplied acls. The entry has no name.

Rate limit

100 requests per minute for each authenticated user, on the admin:user:modify bucket.

Revoke Admin API key

DELETE/v1/admin/api-keys/{key_id}Audit reason

Revokes an Admin API key and returns HTTP 200 with a response body. Requires admin_api_key:manage.

The credential stops authenticating on its next use. A request already in flight runs to completion.

Revocation is permanent

Every later request presenting that credential fails authentication, and no operation recovers the key ID or reissues the raw value.

Path parameters

Field	Type	Description
key_id	snowflake	The ID of the key

Response body

Field	Type	Description
success	boolean	Always true

Response

Status	Body	Condition
200	response body	Key was revoked
404	error response	ADMIN_API_KEY_NOT_FOUND, which also covers an expired key and a key created by another account

Side effects

The operation records one Admin audit entry with action revoke_admin_api_key, target type admin_api_key, target ID equal to key_id, and no metadata.

Rate limit

100 requests per minute for each authenticated user, on the admin:user:modify bucket.