Skip to content

API keys

Manage API keys for the authenticated user.

These endpoints are not available via OAuth — they require a session or API-key credential. The key value (token) is returned only when the key is created; it is never returned again.

In the browser, manage your personal API keys under API keys in your account settings. The endpoints below manage the same keys.

Each key can carry an IP allow list (allowed_ips). An empty list means any address may use the key; otherwise a request from an address outside the list is treated like one with an invalid key.


List API Keys

GET /api/api_keys

Returned Params
  • api_keys: Array<Object>
    • id: Integer
    • name: String
    • allowed_ips: Array<String> | the key's allow list, each entry an address or CIDR range; empty when unrestricted
    • created_at: DateTime
    • updated_at: DateTime

View an API Key

GET /api/api_keys/:id

Returned Params
  • api_key: Object
    • id: Integer
    • name: String
    • allowed_ips: Array<String> | the key's allow list, each entry an address or CIDR range; empty when unrestricted
    • created_at: DateTime
    • updated_at: DateTime

Create an API Key

POST /api/api_keys

Created keys are always non-admin and not system-managed.

Params
  • api_key: Object
    • name: String
    • allowed_ips: Array<String> | optional. IPv4 or IPv6 addresses or CIDR ranges, at most 20. A single string with entries separated by new lines, commas, semicolons or spaces is also accepted.
Errors
  • 422 invalid_api_key | the key failed validation (for example, a blank name)
  • 422 invalid_allowed_ips | an entry is not a valid address or range; nothing is saved
  • 422 too_many_allowed_ips | more than 20 entries
Returned Params
  • api_key: Object
    • id: Integer
    • name: String
    • token: String | Returned only on creation — store it now.
    • allowed_ips: Array<String>
    • created_at: DateTime
    • updated_at: DateTime

Rename an API Key or change its IP allow list

PATCH /api/api_keys/:id

Omit allowed_ips to leave the list unchanged. Sending a list replaces it; an empty array or an empty string clears it, so any address may use the key. One invalid entry fails the whole request and nothing is changed. Returns the key in the same shape as View an API Key, with the same errors as Create an API Key.

Params
  • api_key: Object
    • name: String
    • allowed_ips: Array<String> | optional; see above

Delete an API Key

DELETE /api/api_keys/:id

Returns 202.