Manage API Keys

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>"

const response = await blnk.ApiKeys.list({
  owner: 'payments-team',
});

keys, resp, err := client.ApiKeys.List(&blnkgo.ListApiKeysOptions{
    Owner: "payments-team",
})

response = blnk.api_keys.list({
  "owner": "payments-team",
})

ApiResponse<JsonNode> response = blnk.apiKeys().list(
    ListApiKeysOptions.create()
        .owner("payments-team"));

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>"

const response = await blnk.ApiKeys.delete(
  'api_key_879f0ecb-e29f-4137-801b-1048366381db',
  {
    owner: 'payments-team',
  },
);

resp, err := client.ApiKeys.Delete(
    "api_key_879f0ecb-e29f-4137-801b-1048366381db",
    &blnkgo.DeleteApiKeysOptions{
        Owner: "payments-team",
    },
)

response = blnk.api_keys.delete(
  "api_key_879f0ecb-e29f-4137-801b-1048366381db",
  {
    "owner": "payments-team",
  },
)

ApiResponse<JsonNode> response = blnk.apiKeys().delete(
    "api_key_879f0ecb-e29f-4137-801b-1048366381db",
    DeleteApiKeyOptions.create()
        .owner("payments-team"));

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"
  }'

const response = await blnk.ApiKeys.create({
  name: 'Nightly Reconciliation Job',
  owner: 'payments-team',
  scopes: ['reconciliation:read'],
  expires_at: '2027-01-01T00:00:00Z',
});

expiresAt, _ := time.Parse(time.RFC3339, "2027-01-01T00:00:00Z")
apiKey, resp, err := client.ApiKeys.Create(blnkgo.CreateApiKeyRequest{
    Name: "Nightly Reconciliation Job",
    Owner: "payments-team",
    Scopes: []string{"reconciliation:read"},
    ExpiresAt: expiresAt,
})

response = blnk.api_keys.create({
  "name": "Nightly Reconciliation Job",
  "owner": "payments-team",
  "scopes": ["reconciliation:read"],
  "expires_at": "2027-01-01T00:00:00Z",
})

ApiResponse<JsonNode> response = blnk.apiKeys().create(
    CreateApiKeyData.create()
        .name("Nightly Reconciliation Job")
        .owner("payments-team")
        .scopes(List.of("reconciliation:read"))
        .expiresAt("2027-01-01T00:00:00Z"));

Rotate a key

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"
  }'

const response = await blnk.ApiKeys.create({
  name: 'Payments Service',
  owner: 'payments-team',
  scopes: ['transactions:write', 'balances:read'],
  expires_at: '2027-06-13T00:00:00Z',
});

expiresAt, _ := time.Parse(time.RFC3339, "2027-06-13T00:00:00Z")
apiKey, resp, err := client.ApiKeys.Create(blnkgo.CreateApiKeyRequest{
    Name: "Payments Service",
    Owner: "payments-team",
    Scopes: []string{"transactions:write", "balances:read"},
    ExpiresAt: expiresAt,
})

response = blnk.api_keys.create({
  "name": "Payments Service",
  "owner": "payments-team",
  "scopes": ["transactions:write", "balances:read"],
  "expires_at": "2027-06-13T00:00:00Z",
})

ApiResponse<JsonNode> response = blnk.apiKeys().create(
    CreateApiKeyData.create()
        .name("Payments Service")
        .owner("payments-team")
        .scopes(List.of("transactions:write", "balances:read"))
        .expiresAt("2027-06-13T00:00:00Z"));

Copy the plaintext key value from the response immediately. You won’t see it again.

Update your applications

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

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>"

const response = await blnk.ApiKeys.delete(
  'api_key_879f0ecb-e29f-4137-801b-1048366381db',
  {
    owner: 'payments-team',
  },
);

resp, err := client.ApiKeys.Delete(
    "api_key_879f0ecb-e29f-4137-801b-1048366381db",
    &blnkgo.DeleteApiKeysOptions{
        Owner: "payments-team",
    },
)

response = blnk.api_keys.delete(
  "api_key_879f0ecb-e29f-4137-801b-1048366381db",
  {
    "owner": "payments-team",
  },
)

ApiResponse<JsonNode> response = blnk.apiKeys().delete(
    "api_key_879f0ecb-e29f-4137-801b-1048366381db",
    DeleteApiKeyOptions.create()
        .owner("payments-team"));

Confirm your applications no longer reference the old key.

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>"

const response = await blnk.ApiKeys.list({
  owner: 'payments-team',
});

keys, resp, err := client.ApiKeys.List(&blnkgo.ListApiKeysOptions{
    Owner: "payments-team",
})

response = blnk.api_keys.list({
  "owner": "payments-team",
})

ApiResponse<JsonNode> response = blnk.apiKeys().list(
    ListApiKeysOptions.create()
        .owner("payments-team"));

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.

Code	When it happens
`APIKEY_INVALID`	The create request failed validation.
`APIKEY_OWNER_REQUIRED`	The master key was used to create or list keys without an `owner` parameter.
`APIKEY_NOT_FOUND`	The 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:

Code	What to do
`APIKEY_OWNER_REQUIRED`	Add the `owner` query parameter or body field when using the master key.
`APIKEY_INVALID`	Fix the validation issue in the create request (missing fields, invalid scopes, or malformed dates).
`APIKEY_NOT_FOUND`	Verify 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.

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

List keys

Revoke a key

Delegate key creation

Rotate a key

Security best practices

Error handling

Need help?

​List keys

​Revoke a key

​Delegate key creation

​Rotate a key

​Security best practices

​Error handling

​Need help?

List keys

Revoke a key

Delegate key creation

Rotate a key

Security best practices

Error handling

Need help?