API Keys

Partner API keys authenticate server-to-server requests for wallet provisioning and token deploys. Keys are scoped to your organization and passed via the X-Partner-Key header.

Key Format

bk_ptr_<keyId>_<secret>

• keyId — 8-character identifier
• secret — 32-character secret (hashed at rest, never stored in plaintext)

The full key is only returned once at creation time. Store it securely.

Managing Keys

Generate, view, and revoke partner keys from the Partner Keys tab in your partner dashboard. You can create up to 5 active keys per organization.

When generating a key:

• Name — 3–64 characters, for your own reference
• IP allowlist — optionally restrict the key to specific IP addresses

Save your secret

The full key is only shown once after creation. Copy and store it securely — you cannot retrieve it later.

Revoked keys stop working immediately. This cannot be undone — generate a new key if needed.

---

Using a Partner Key

Include the key in the X-Partner-Key header on every server-to-server request:

curl -X POST https://api.bankr.bot/partner/wallets \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: bk_ptr_AbC12345_xYzSecretKeyValue1234567890ab" \
  -d '{ ... }'

Errors

Status	Error	Cause
401	Partner API key required	Missing X-Partner-Key header
401	The provided partner API key is invalid or inactive	Key not found, revoked, or wrong secret
403	IP address not allowed for this partner API key	Request IP not in allowedIps
403	The partner organization associated with this key is inactive	Org deactivated

---

IP Allowlisting

When an IP allowlist is set on a key, only requests from those IPs are accepted. Supports individual IPs and CIDR ranges (e.g., 10.0.0.0/24). IPv6-mapped IPv4 addresses (e.g., ::ffff:192.168.1.1) are automatically normalized.

Minimum CIDR prefix lengths are enforced: /8 for IPv4, /16 for IPv6. Overly broad ranges (e.g., 0.0.0.0/0) are rejected.

Update a partner key's allowlist via the partner dashboard or PATCH /partner/:orgId/api-keys/:keyId with { "allowedIps": ["10.0.0.0/24", "203.0.113.1"] }.

---

Wallet API Keys

Provisioned wallets have their own API keys (format bk_usr_{keyId}_{secret}) separate from partner keys. Those keys authenticate end-user traffic (wallet operations, agent API, etc.) scoped to a single provisioned wallet.

A wallet may have up to 20 active keys. Each POST appends a new key; use the per-key DELETE to revoke one.

Manage them via the partner API:

Method	Endpoint	Purpose
GET	/partner/wallets/:identifier/api-keys	List all keys on a wallet
GET	/partner/wallets/:identifier/api-keys/:keyId	Fetch detail (IPs, recipients, permissions)
POST	/partner/wallets/:identifier/api-keys	Create a new key (appends; up to 20 active per wallet). Optional name.
PATCH	/partner/wallets/:identifier/api-keys/:keyId	Update name, IPs, trusted recipients, or permissions in place (no secret rotation)
POST	/partner/wallets/:identifier/api-keys/:keyId/rotate	Atomically rotate: create a new key with the same config, deactivate the old one
DELETE	/partner/wallets/:identifier/api-keys/:keyId	Revoke one specific key
DELETE	/partner/wallets/:identifier/api-keys	Revoke all active keys on the wallet

Rotation

POST /api-keys/:keyId/rotate is the simplest path — it copies the old key's name, permissions, IP allowlist, and recipient allowlist onto a new key and deactivates the old one in a single transaction. The new secret is returned once.

For zero-downtime rotation with a migration window, use the manual flow instead: POST /api-keys to create a new key, migrate consumers, then DELETE /api-keys/:keyId to revoke the old one.

Examples

Update the IP allowlist on an existing wallet key:

curl -X PATCH https://api.bankr.bot/partner/wallets/wlt_j7Qm4rT9/api-keys/a1b2c3d4 \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: bk_ptr_..." \
  -d '{ "allowedIps": ["203.0.113.10"] }'

PATCH body fields are all optional; at least one of name, allowedIps, allowedRecipients, or permissions must be present.

Revoke a specific key:

curl -X DELETE https://api.bankr.bot/partner/wallets/wlt_j7Qm4rT9/api-keys/a1b2c3d4 \
  -H "X-Partner-Key: bk_ptr_..."

Capabilities that your organization has disabled (configured via Bankr team) cannot be enabled on individual keys — attempting to do so returns 403.