0.12.0 Migration Guide

Identify all places in your codebase where API keys are retrieved or used:

1. Check for code that reads API keys from GET /api-keys
   • Any code that expects to use the key field from list responses.
   • Automation scripts that retrieve keys after creation.
   • Migration scripts that read existing API keys.
2. Identify API key storage locations
   • Where you currently store API keys.
   • How you retrieve them for authentication.
   • Any caching mechanisms that rely on plain text keys.

Ensure you store the plain text key immediately after creation:

curl -X POST "http://localhost:5001/api-keys" \
  -H "X-blnk-key: <master-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "owner": "my-owner-id",
    "scopes": ["ledgers:read", "balances:write"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

{
  "api_key_id": "api_key_123...",
  "key": "g-nnlP_kfxOP42baBGFJ",
  "name": "My API Key",
  "owner_id": "my-owner-id"
}

Store the key securely:

• Environment variables.
• Secret management systems (AWS Secrets Manager, HashiCorp Vault, etc.).
• Secure configuration files (excluded from version control).

Remove any code that expects plain text keys from the list endpoint:

const response = await fetch('/api-keys?owner=my-owner');
const keys = await response.json();
const apiKey = keys[0].key;

const createResponse = await fetch('/api-keys', {
  method: 'POST',
  headers: {
    'X-Blnk-Key': masterKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Key',
    owner: 'my-owner',
    scopes: ['*:*'],
    expires_at: '2026-12-31T23:59:59Z'
  })
});
const newKey = await createResponse.json();
const plainTextKey = newKey.key;

const authHeaders = {
  'X-Blnk-Key': plainTextKey
};

The list response key is now a hash, so using it for authentication fails. Store the plain text key from the create response and send that stored value on later requests.

Before upgrading, or immediately after:

1. Identify all existing API keys that are currently in use.
2. Create new API keys with the same scopes and permissions.
3. Store the new plain text keys securely immediately after creation.
4. Update your applications to use the new keys.
5. Test authentication with the new keys.
6. Revoke old API keys once migration is complete.

Test that authentication works correctly:

curl -X GET "http://localhost:5001/ledgers" \
  -H "X-blnk-key: <your-stored-plain-text-key>"

Authentication works with the stored plain text key. The system hashes incoming keys and compares them with the stored hashes.