Scoped API Keys

Available on Blnk Core 0.10.1 and later.

Your master key has full access to your Blnk server. Use it only for admin actions, like creating and revoking API keys. For everything else, use scoped API keys. Each key can be limited to a specific owner, set of scopes, and expiry date. For example, your payments service might only need transactions:write and balances:read, while your reporting service might only need *:read. This keeps each service limited to the access it needs. If a key is exposed, you can revoke that key without rotating your master key or affecting the rest of your system.

Before you start

Scoped API keys require secure mode. When secure mode is enabled, Blnk requires every request to include a valid key in the X-Blnk-Key header. Start by enabling secure mode and setting a strong secret_key in your configuration:

BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY=your_strong_secret_key

{
  "server": {
    "secure": true,
    "secret_key": "your_strong_secret_key"
  }
}

The secret_key becomes your master key. Use it once to create your first scoped API key with POST /api-keys. After that, use scoped keys for normal API traffic.

Do not commit the master key to version control. In production, store it in a secret manager or inject it through environment variables.

Create and use a scoped key

Create a scoped key

Use the master key to create your first scoped key. In this example, we create a key for a payments service:

curl -X POST "http://localhost:5001/api-keys" \
  -H "X-blnk-key: <master-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"));

Parameter	Description
`name`	A readable label for the key, such as a service or environment name.
`owner`	The team, service, or tenant that owns the key. Blnk stores this as `owner_id`. See Owner context.
`scopes`	The permissions assigned to the key, using `resource:action` format. See Scopes.
`expires_at`	When the key stops working, in ISO 8601 format.

A successful request returns 201 Created.

Save the key

On success, the response includes the plaintext key in the key field:

201 Created

{
  "api_key_id": "api_key_879f0ecb-e29f-4137-801b-1048366381db",
  "key": "YVLIhuIplUzLRCcT9r7DQ_jsGKCXAn39JQ3n_o-Ll2Q=",
  "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": "0001-01-01T00:00:00Z",
  "is_revoked": false
}

Copy the key value immediately and store it in your secrets manager or as an environment variable. Wire that value into the service that will call Blnk.

Blnk shows the plaintext key only once. After creation, the key is hashed at rest and cannot be retrieved again.If you lose it, create a new key and revoke the old one.

Use the scoped key

Pass the scoped key in the X-Blnk-Key header on every request.

curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <scoped-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 10000,
    "reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
    "currency": "USD",
    "precision": 100,
    "source": "bln_a1b2c3d4-6e2d-4f89-a17b-3d5e8f2a1c94",
    "destination": "bln_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
    "description": "Payment transfer",
    "allow_overdraft": true
  }'

const response = await blnk.Transactions.create({
  precise_amount: 10000,
  reference: 'ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
  currency: 'USD',
  precision: 100,
  source: 'bln_a1b2c3d4-6e2d-4f89-a17b-3d5e8f2a1c94',
  destination: 'bln_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
  description: 'Payment transfer',
  allow_overdraft: true,
});

baseURL, _ := url.Parse("http://localhost:5001/")
scopedKey := os.Getenv("BLNK_SCOPED_API_KEY")
client := blnkgo.NewClient(baseURL, &scopedKey)

transaction, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
    ParentTransaction: blnkgo.ParentTransaction{
        PreciseAmount: big.NewInt(10000),
        Reference: "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
        Currency: "USD",
        Precision: 100,
        Source: "bln_a1b2c3d4-6e2d-4f89-a17b-3d5e8f2a1c94",
        Destination: "bln_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
        Description: "Payment transfer",
    },
    AllowOverdraft: true,
})

response = blnk.transactions.create({
  "precise_amount": 10000,
  "reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "currency": "USD",
  "precision": 100,
  "source": "bln_a1b2c3d4-6e2d-4f89-a17b-3d5e8f2a1c94",
  "destination": "bln_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "description": "Payment transfer",
  "allow_overdraft": True,
})

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(10000)
        .reference("ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
        .currency("USD")
        .precision(100)
        .source("bln_a1b2c3d4-6e2d-4f89-a17b-3d5e8f2a1c94")
        .destination("bln_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
        .description("Payment transfer")
        .allowOverdraft(true));

Blnk checks that the key is valid, not expired or revoked, and that its scopes cover the endpoint you’re calling. This key has transactions:write, so it can create transactions but cannot create ledgers without ledgers:write.

API key tracking

When you create a record with a scoped API key, Blnk adds the key’s api_key_id to the resource meta_data under BLNK_GENERATED_BY. This lets you trace which key created a ledger, balance, transaction, or identity. The master key does not add this field. Only scoped API keys authenticated through X-Blnk-Key do.

API key tracking

"meta_data": {
  "purpose": "customer_wallet",
  "BLNK_GENERATED_BY": "api_key_879f0ecb-e29f-4137-801b-1048366381db"
}

Blnk sets BLNK_GENERATED_BY automatically on POST requests. You do not need to include it in your request body. If you send your own meta_data, Blnk merges this field into it.

You can use BLNK_GENERATED_BY for audit trails, service attribution, and tenant-level tracing. For example, if each tenant or service uses its own scoped key, you can filter records by meta_data.BLNK_GENERATED_BY to see what that key created.

Error handling

Structured errors are available from Blnk Core 0.15.0 and later.

When a scoped key fails authentication, Blnk returns a 401 Unauthorized response.

Code	When it happens
`AUTH_INVALID_API_KEY`	The key is incorrect, malformed, incomplete, or sent with the wrong header.
`AUTH_EXPIRED_API_KEY`	The key has expired or has been revoked.

401 Unauthorized

{
  "error": "API key is expired or revoked",
  "error_detail": {
    "code": "AUTH_EXPIRED_API_KEY",
    "message": "API key is expired or revoked"
  }
}

To resolve the error:

Code	What to do
`AUTH_INVALID_API_KEY`	Check that the full key value is being sent in the `X-Blnk-Key` header.
`AUTH_EXPIRED_API_KEY`	Create a replacement key with the same scopes, update the service using it, then revoke the old key. See Manage API keys.

Other authentication errors, such as a missing X-Blnk-Key header, are covered in Secure your Blnk server.

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

Before you start

Create and use a scoped key

API key tracking

Error handling

Need help?

​Before you start

​Create and use a scoped key

​API key tracking

​Error handling

​Need help?

Before you start

Create and use a scoped key

API key tracking

Error handling

Need help?