> ## 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.
# API Key Scopes
> Choose the right permissions for each API key using 'resource:action' scopes.
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 ;
};
Scopes control what an API key is allowed to do.
Each scope uses `resource:action` format. For example, `ledgers:read` allows a key to read ledgers, while `transactions:write` allows it to create transactions.
Instead of giving every service full access, use scopes to create keys that match what each service actually does.
These patterns cover most setups:
| Use case | Scopes | What the key can do |
| :------------------ | :--------------------------------------------------- | :------------------------------------- |
| Read-only reporting | `ledgers:read`, `balances:read` | View ledgers and balances |
| Payment processing | `transactions:write`, `balances:read` | Create transactions and check balances |
| Identity management | `identities:write`, `identities:read` | Create and view identities |
| Key administration | `api-keys:read`, `api-keys:write`, `api-keys:delete` | Manage keys within its owner context |
Avoid `*:*` unless you truly need full access. For most cases, create a scoped key with only the permissions required.
***
## How scopes work
Each scope has two parts: a resource and an action, separated by a colon: `resource:action`.
The resource defines the area of Blnk the key can access. The action defines what the key can do in that area.
| Resource | Description |
| :----------------- | :--------------------- |
| `*` | All resources |
| `ledgers` | Ledger management |
| `balances` | Balance operations |
| `accounts` | Account operations |
| `identities` | Identity management |
| `transactions` | Transaction processing |
| `balance-monitors` | Balance monitoring |
| `api-keys` | API key management |
| `search` | Search operations |
| `reconciliation` | Reconciliation tasks |
| `metadata` | Metadata management |
| `backup` | Backup operations |
Blnk maps HTTP methods to actions automatically:
| Action | HTTP methods | Description |
| :------- | :--------------------- | :--------------------------- |
| `*` | Any | All actions on the resource |
| `read` | `GET`, `HEAD` | View operations |
| `write` | `POST`, `PUT`, `PATCH` | Create and modify operations |
| `delete` | `DELETE` | Delete operations |
You can use `*` as a wildcard on either side. `ledgers:*` grants all ledger actions. `*:read` grants read access to every resource.
Hook management requires the [master key](/advanced/secure-blnk#master-key). Scoped keys cannot manage hooks.
***
## Error handling
Structured errors are available from Blnk Core 0.15.0 and later.
When a scoped key is valid but lacks permission for the endpoint you called, Blnk returns a `403 Forbidden` response.
| Code | When it happens |
| :------------------------------ | :------------------------------------------------------------- |
| `AUTH_INSUFFICIENT_PERMISSIONS` | The key is missing the scope required for that endpoint. |
| `AUTH_UNKNOWN_RESOURCE` | The request path does not map to a known Blnk resource. |
| `AUTH_MASTER_KEY_REQUIRED` | The endpoint requires the master key, such as hook management. |
```json 403 Forbidden wrap theme={"system"}
{
"error": "Insufficient permissions for transactions:write",
"error_detail": {
"code": "AUTH_INSUFFICIENT_PERMISSIONS",
"message": "Insufficient permissions for transactions:write"
}
}
```
To resolve the error:
| Code | What to do |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
| `AUTH_INSUFFICIENT_PERMISSIONS` | Check which scope the endpoint needs, then create a new key with that scope or call an endpoint the key already covers. |
| `AUTH_UNKNOWN_RESOURCE` | Verify the request path matches a supported API route. |
| `AUTH_MASTER_KEY_REQUIRED` | Use the [master key](/advanced/secure-blnk#master-key) for that operation. |
***
## Related docs
Create and use scoped keys.
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.