API Keys

An API key is one version of a consumer's credential. A consumer's keys are listed and rolled at …/consumers/{consumerId}/api-keys, and each key is addressed by its ID, /v4/buckets/{bucketId}/api-keys/{apiKeyId}, for example to revoke a leaked key without looking up its consumer.

Rolling is creating the replacement: a new key for the consumer, whose other keys expire right away or after previousKeyGracePeriodSeconds. Outside a roll's grace period, a consumer has one working key.

The full secret is returned when a key is created. After that, reads show only maskedKey. The one exception is a person's own consumers in a user app: the person reads a key's secret at …/api-keys/{apiKeyId}/secret, for example for a key an admin issued for them. The secret belongs to a key, not to its consumer, which can have several keys during a roll's grace period.

Get an API key

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/api-keys/{apiKeyId}

Returns an API key and the consumer it belongs to, with only the masked key. List a consumer's keys at …/consumers/{consumerId}/api-keys. Anyone who can read the key's consumer can read the key.

Get an API key › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

apiKeyId

string · maxLength: 64 · required

The API key ID (key_…). This is the key's identifier, not its secret.

Get an API key › Responses

The API key.

An API key, one version of its consumer's credential, without its secret.

ApiKey

id

string · required

The key ID. Not the secret.

Example: key_XKrbtT8H72PH0gQpblaXfstB

consumerId

string · required

The consumer the key belongs to.

Example: csmr_brw0leTAVw478VFKD4F6OqVI

description

string | null · required

What the key is used for.

Example: Production backend

maskedKey

string · required

The first and last characters of the secret, to recognize the key.

Example: zpka_xxxx…xxxx

expiresOn

string | null · date-time · required

When the key stops working, or null if it never expires.

createdOn

string · date-time · required

When the key was created.

updatedOn

string · date-time · required

When the key was last changed.

Update an API key

PATCH

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/api-keys/{apiKeyId}

Updates an API key's description or expiry with JSON Merge Patch semantics. A key cannot move to another consumer. Anyone who can change the key's consumer can change the key; others get 403.

Update an API key › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

apiKeyId

string · maxLength: 64 · required

The API key ID (key_…). This is the key's identifier, not its secret.

Update an API key › Request Body

Changes to an API key (JSON Merge Patch).

UpdateApiKeyRequest

description

string | null · maxLength: 512

What the key is used for. Null clears it.

expiresOn

string | null · date-time

When the key stops working. Null removes the expiry.

Update an API key › Responses

The updated API key.

An API key, one version of its consumer's credential, without its secret.

ApiKey

id

string · required

The key ID. Not the secret.

Example: key_XKrbtT8H72PH0gQpblaXfstB

consumerId

string · required

The consumer the key belongs to.

Example: csmr_brw0leTAVw478VFKD4F6OqVI

description

string | null · required

What the key is used for.

Example: Production backend

maskedKey

string · required

The first and last characters of the secret, to recognize the key.

Example: zpka_xxxx…xxxx

expiresOn

string | null · date-time · required

When the key stops working, or null if it never expires.

createdOn

string · date-time · required

When the key was created.

updatedOn

string · date-time · required

When the key was last changed.

Revoke an API key

DELETE

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/api-keys/{apiKeyId}

Revokes an API key immediately, for example when it leaked or to end a roll's grace period early. Its ID is enough: you do not need its consumer. A repeated delete returns 404, which clients should treat as success. Anyone who can change the key's consumer can revoke the key; others get 403.

Revoke an API key › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

apiKeyId

string · maxLength: 64 · required

The API key ID (key_…). This is the key's identifier, not its secret.

Revoke an API key › Responses

The key was revoked.

No data returned

Get an API key's secret

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/api-keys/{apiKeyId}/secret

Returns the full secret of one key of a personal consumer to the person who holds the consumer. Nobody else can read it, user app admins included: they see the secret only in the response that created the key. The keys of app and bucket consumers show their secret only when they are created, so this fails with 403 for them. Find the key in the consumer's keys, GET …/consumers/{consumerId}/api-keys, which lists the newest first.

The response must not be stored (Cache-Control: no-store).

Get an API key's secret › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

apiKeyId

string · maxLength: 64 · required

The API key ID (key_…). This is the key's identifier, not its secret.

Get an API key's secret › Responses

The key's secret.

The secret of a key of a personal consumer, which only the person who holds the consumer can read.

ApiKeySecret

apiKeyId

string · required

The key the secret belongs to.

Example: key_XKrbtT8H72PH0gQpblaXfstB

secret

string · required

The full API key. Send it as Authorization: Bearer <secret>.

Example: zpka_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxx

List a consumer's API keys

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/consumers/{consumerId}/api-keys

Lists the consumer's keys, newest first: its current key and the keys it replaced. Only masked keys are returned. Anyone who can read the consumer can list its keys.

List a consumer's API keys › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

consumerId

string · maxLength: 64 · required

The consumer ID (csmr_…).

List a consumer's API keys › query Parameters

limit

integer · min: 1 · max: 100

The maximum number of items to return.

Default: 10

offset

integer · min: 0

The number of items to skip before the first item returned.

Default: 0

List a consumer's API keys › Responses

A page of the consumer's API keys.

A page of API keys.

ApiKeyList

ApiKey[] · required

The API keys on this page.

limit

integer · required

The page size that was applied.

offset

integer · required

The number of items skipped before this page.

total

integer · required

The number of items in the whole collection.

hasMore

boolean · required

Whether there are more items after this page.

next

string | null · required

The relative URL of the next page, or null on the last page.

Roll a consumer's API key

POST

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/consumers/{consumerId}/api-keys

Issues a new key for the consumer, which is how a key is rolled: the consumer's other keys expire right away, or after the previousKeyGracePeriodSeconds in the query so its clients can switch over. A key that already expires sooner keeps its expiry. The body is the new key. Anyone who can change the consumer can roll it; pool admins cannot roll an app's consumer, and get 403. A consumer that holds a subscription (API monetization) cannot be rolled through v4 and gets 409.

The response contains the full secret. This is the only time it is returned to the caller, so store it now. A retry issues another key, which replaces this one, so keep the key from the last response.

Roll a consumer's API key › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

consumerId

string · maxLength: 64 · required

The consumer ID (csmr_…).

Roll a consumer's API key › query Parameters

previousKeyGracePeriodSeconds

integer · min: 0 · max: 2592000

How long the consumer's other keys keep working after the new key is issued, in seconds (at most 30 days). Omit or send 0 to expire them right away. A key that already expires sooner keeps its expiry.

Default: 0

Roll a consumer's API key › Request Body

A new key for a consumer, which replaces its other keys. Send `{}` for a key without description or expiry.

CreateConsumerApiKeyRequest

description

string | null · maxLength: 512

What the key is used for.

expiresOn

string | null · date-time

When the key stops working. Omit for a key that never expires.

Roll a consumer's API key › Responses

The key was created. secret is shown only in this response.

A newly created API key, including its secret, which is shown only once.

ApiKeyWithSecret

id

string · required

The key ID. Not the secret.

Example: key_XKrbtT8H72PH0gQpblaXfstB

consumerId

string · required

The consumer the key belongs to.

Example: csmr_brw0leTAVw478VFKD4F6OqVI

description

string | null · required

What the key is used for.

maskedKey

string · required

The first and last characters of the secret, to recognize the key later.

Example: zpka_xxxx…xxxx

expiresOn

string | null · date-time · required

When the key stops working, or null if it never expires.

createdOn

string · date-time · required

When the key was created.

updatedOn

string · date-time · required

When the key was last changed.

secret

string · required

The full API key. Send it as Authorization: Bearer <secret>. Returned only in this response.

Example: zpka_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxx

POST/v4/buckets/{bucketId}/consumers/{consumerId}/api-keys

curl https://dev-api-v4-main-a471234.zuplo.app/v4/buckets/:bucketId/consumers/:consumerId/api-keys \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{}'

Example Request Body

{}

json

application/json

Example Responses

{
  "id": "key_XKrbtT8H72PH0gQpblaXfstB",
  "consumerId": "csmr_brw0leTAVw478VFKD4F6OqVI",
  "description": "description",
  "maskedKey": "zpka_xxxx…xxxx",
  "expiresOn": "2024-08-25T15:00:00Z",
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z",
  "secret": "zpka_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxx"
}

json

application/json

Consumers