> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Scoped API Keys
> Create scoped API keys so each service gets only the permissions it needs.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
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:
```bash blnk.env theme={"system"}
BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY=your_strong_secret_key
```
```json blnk.json theme={"system"}
{
"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
Use the master key to create your first scoped key. In this example, we create a key for a payments service:
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/api-keys" \
-H "X-blnk-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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.ApiKeys.create({
name: 'Payments Service',
owner: 'payments-team',
scopes: ['transactions:write', 'balances:read'],
expires_at: '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](/api-keys/owner-context). |
| `scopes` | The permissions assigned to the key, using `resource:action` format. See [Scopes](/api-keys/scopes). |
| `expires_at` | When the key stops working, in ISO 8601 format. |
A successful request returns `201 Created`.
On success, the response includes the plaintext key in the `key` field:
```json 201 Created wrap theme={"system"}
{
"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.
Pass the scoped key in the `X-Blnk-Key` header on every request.
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/transactions" \
-H "X-blnk-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
}'
```
```typescript TypeScript wrap theme={"system"}
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,
});
```
```go Go wrap theme={"system"}
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: 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.
```json API key tracking wrap theme={"system"}
"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. |
```json 401 Unauthorized wrap theme={"system"}
{
"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](/api-keys/manage-keys). |
Other authentication errors, such as a missing `X-Blnk-Key` header, are covered in [Secure your Blnk server](/advanced/secure-blnk#error-handling).
***
## Related docs
Pick the right permissions.
How Blnk isolates key management.
List, revoke, and delegate keys.
***
## 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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.