Operating

API Key Owner Context

Understand how owner labels isolate API key management across teams and services.

Every API key belongs to an owner.

The owner is a label you choose when creating the key, such as a team name, service name, or tenant ID. Blnk stores this value as owner_id on the key record.

Owner context controls which keys a scoped key can manage. A scoped key can only create, list, and revoke keys that belong to its own owner_id. It cannot manage keys for another owner.

Example scenario

Say you create two keys under different owners:

• Key k1 has owner_id = merchant_a
• Key k2 has owner_id = merchant_b

If k1 is used to manage API keys, Blnk resolves the owner as merchant_a.

That means k1 can manage keys for merchant_a, but it cannot manage keys for merchant_b, even if the request includes "owner": "merchant_b".

Delegated key management

Scoped keys can manage API keys, but only within their own owner context.

This lets a team admin create narrower service keys for a team, service, or tenant without handing out the master key. For example, a key with api-keys:read, api-keys:write, and api-keys:delete can create, list, and revoke keys for its own owner_id.

Two rules apply to scoped keys:

1. Scope inheritance. A key can only grant scopes it already has. For example, a key with only transactions:read cannot create another key with transactions:write.

2. No cross-owner access. The effective owner always comes from the caller’s stored owner_id. A key for merchant_a cannot create, list, or revoke keys for merchant_b.

Error handling

When a key management request breaks owner or delegation rules, Blnk returns a 400, 403, or 404 response.

Blnk does not always return 403 for cross-owner requests.

For example, trying to revoke another owner’s key returns 404 APIKEY_NOT_FOUND instead of 403. This prevents the response from revealing whether that key exists under another owner.

Listing keys with ?owner=another-team returns 403 AUTH_CROSS_OWNER_ACCESS, because the request is explicitly trying to access another owner’s key list.

Example response:

{
  "error": "cannot grant scopes broader than caller",
  "error_detail": {
    "code": "AUTH_SCOPE_ESCALATION",
    "message": "cannot grant scopes broader than caller"
  }
}

To resolve the error: