Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview

List the org's API keys (secrets are never returned)

Lists the keys that are not revoked, expired ones included: every key of the org for an owner’s or admin’s key, only the user’s own keys for a member’s key. Keys are created and revoked on the website’s account page.

GET/v1/api-keys
Authorization
AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Responses
200

The keys, newest first.

api_keysAPIKey[]required
Show properties
Array of APIKey
idstringrequired
namestringrequired
prefixstringrequired

The non-secret start of the key, for recognising it.

created_atstring<date-time>required
last_used_atstring<date-time> | null
expires_atstring<date-time> | null

When the key stops working; absent or null means never.

created_bystring | null

Who created the key: web:<user id> for a key made on my.pols.so/account; absent or null for keys made by the operator CLI or before creators were recorded, including keys made through the API before it stopped creating keys.

user_emailstring | null

The email address of the user the key belongs to and acts as, with that user's current role in role. Both are absent for a key whose user is gone.

roleRole

What a user, and each of their API keys, may do in the org. owner: everything, including making and removing owners. admin: manages the members other than owners, every API key of the org and the vault on the website, and uses sandboxes. member: uses sandboxes, manages their own API keys and sees the vault's names. Every org has at least one owner.

Allowed:owneradminmember
429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

Request
curl -X GET 'https://api.pols.so/v1/api-keys' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "api_keys": [
    {
      "id": "key_8f2k1m9x0q3z",
      "name": "string",
      "prefix": "pols_8f2k1m9x0q3z",
      "created_at": "2019-08-24T14:15:22Z",
      "last_used_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "created_by": "web:usr_3k9m2x7q1z0a",
      "user_email": "dev@example.com",
      "role": "owner"
    }
  ]
}