Skip to main content
After you create a scoped key, you’ll audit what’s active, revoke keys you no longer need, and rotate keys before they expire. If you haven’t created a key yet, start with Scoped API keys. Listing, revoking, and delegating keys requires the master key or a scoped key with the matching api-keys:* scopes. See Scopes for permissions and Owner context for which keys a caller can manage.

​
List keys

List keys for an owner to see what’s active. The plaintext key value is never returned. You get metadata such as name, scopes, expiry, and last-used timestamp. 
curl -X GET "http://localhost:5001/api-keys?owner=payments-team" \
  -H "X-blnk-key: <api-key>"
200 OK
[
  {
    "api_key_id": "api_key_879f0ecb-e29f-4137-801b-1048366381db",
    "name": "Payments Service",
    "owner_id": "payments-team",
    "scopes": ["transactions:write", "balances:read"],
    "expires_at": "2027-06-13T00:00:00Z",
    "created_at": "2026-06-13T10:30:00Z",
    "last_used_at": "2026-06-13T14:22:00Z"
  }
]

​
Revoke a key

Revoke a key when it’s no longer needed or you suspect it was exposed. 
curl -X DELETE "http://localhost:5001/api-keys/api_key_879f0ecb-e29f-4137-801b-1048366381db?owner=payments-team" \
  -H "X-blnk-key: <api-key>"
A successful revoke returns 204 No Content with an empty body. The key stops working on the next request.
Revoking a key takes effect immediately. Deploy a replacement key before revoking the old one.

​
Delegate key creation

Available on Blnk Core 0.14.3 and later.
A scoped key with api-keys:write can create narrower keys for its own owner, as long as it only grants scopes it already holds. See Owner context for inheritance and cross-owner rules. 
curl -X POST "http://localhost:5001/api-keys" \
  -H "X-blnk-key: <team-admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Reconciliation Job",
    "owner": "payments-team",
    "scopes": ["reconciliation:read"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

​
Rotate a key

1

Create the replacement key

Create a new key with the same scopes or tighter ones:
curl -X POST "http://localhost:5001/api-keys" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments Service",
    "owner": "payments-team",
    "scopes": ["transactions:write", "balances:read"],
    "expires_at": "2027-06-13T00:00:00Z"
  }'
Copy the plaintext key value from the response immediately. You won’t see it again.
2

Update your applications

Deploy the new key to your secret manager or environment variables. Verify the service works with the new key.
3

Revoke the old key

Delete the old key:
curl -X DELETE "http://localhost:5001/api-keys/api_key_879f0ecb-e29f-4137-801b-1048366381db?owner=payments-team" \
  -H "X-blnk-key: <api-key>"
Confirm your applications no longer reference the old key.
4

Audit

List keys for the owner and confirm only the expected keys remain active:
curl -X GET "http://localhost:5001/api-keys?owner=payments-team" \
  -H "X-blnk-key: <api-key>"

​
Security best practices

  • Review your key list regularly. Look for keys with broad scopes, keys that haven’t been used recently, and keys approaching their expiry date.
  • Create a separate key for each service or environment.
  • Set expiration dates and grant the minimum scopes. See Scopes before each create.
  • Store keys in a secret manager. Never commit them to version control.

​
Error handling

Structured errors are available from Blnk Core 0.15.0 and later.
When a list, create, or revoke request fails validation or owner checks, Blnk returns 400 Bad Request or 404 Not Found.
CodeWhen it happens
APIKEY_INVALIDThe create request failed validation.
APIKEY_OWNER_REQUIREDThe master key was used to create or list keys without an owner parameter.
APIKEY_NOT_FOUNDThe key ID is not found in the caller’s owner context.
400 Bad Request
{
  "error": "owner is required",
  "error_detail": {
    "code": "APIKEY_OWNER_REQUIRED",
    "message": "owner is required"
  }
}
To resolve the error:
CodeWhat to do
APIKEY_OWNER_REQUIREDAdd the owner query parameter or body field when using the master key.
APIKEY_INVALIDFix the validation issue in the create request (missing fields, invalid scopes, or malformed dates).
APIKEY_NOT_FOUNDVerify the key ID and that it belongs to the owner you’re acting on. See Owner context.
Delegation and cross-owner errors are covered in Owner context. Permission errors for missing scopes are covered in Scopes.

Overview

Create and use scoped keys.

Scopes

Pick the right permissions.

Owner context

How Blnk isolates key management.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.