Authentication

Overview

Blnk uses API key authentication to secure access to the API. All authenticated requests must include the X-Blnk-Key header with a valid API key or master key.

Authentication Header

Include your API key in the request header:

X-Blnk-Key

string

required

Your API key or master key for authentication

curl -X GET http://localhost:5001/ledgers \
  -H "X-Blnk-Key: your-api-key-here"

Secure Mode

Authentication can be enabled or disabled based on your environment configuration:

{
  "server": {
    "secure": true,
    "secret_key": "your-master-key"
  }
}

Or via environment variable:

BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY="your-master-key"

When secure is set to false, authentication is bypassed. This should only be used in development environments.

Authentication Types

Master Key

The master key provides unrestricted access to all API resources and operations. It’s configured in your Blnk server settings.

secret_key

string

required

The master secret key configured in your server settings

Configuration:

BLNK_SERVER_SECRET_KEY="your-secure-master-key"

Usage:

curl -X POST http://localhost:5001/api-keys \
  -H "X-Blnk-Key: your-secure-master-key" \
  -H "Content-Type: application/json" \
  -d '{...}'

The master key should be kept secure and only used for administrative operations. Use API keys with limited scopes for regular operations.

API Keys

API keys provide granular, scoped access to specific resources and actions. They can be created, listed, and revoked programmatically.

Key Features:

Scoped permissions: Limit access to specific resources (ledgers, balances, transactions, etc.)
Action-based control: Restrict to read, write, or delete operations
Expiration dates: Set expiry times for enhanced security
Owner tracking: Associate keys with specific users or services
Automatic metadata injection: Track which API key created resources

Creating API Keys

Create a new API key with specific permissions.

Endpoint

POST /api-keys

Request Body

name

string

required

A descriptive name for the API key

owner

string

required

The owner identifier (user ID, service name, etc.)

scopes

array

required

Array of permission scopes in the format resource:action

expires_at

string

required

ISO 8601 timestamp when the key expires (e.g., 2024-12-31T23:59:59Z)

Example Request

curl -X POST http://localhost:5001/api-keys \
  -H "X-Blnk-Key: your-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App Production",
    "owner": "mobile-team",
    "scopes": [
      "ledgers:read",
      "balances:read",
      "balances:write",
      "transactions:write"
    ],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Response

api_key_id

string

Unique identifier for the API key

key

string

The actual API key to use in requests (only returned once)

name

string

The name of the API key

owner

string

The owner identifier

scopes

array

Array of permission scopes

created_at

string

ISO 8601 timestamp of creation

expires_at

string

ISO 8601 timestamp of expiration

last_used_at

string

ISO 8601 timestamp of last usage (null initially)

{
  "api_key_id": "key_1234567890abcdef",
  "key": "blnk_sk_1234567890abcdefghijklmnopqrstuvwxyz",
  "name": "Mobile App Production",
  "owner": "mobile-team",
  "scopes": [
    "ledgers:read",
    "balances:read",
    "balances:write",
    "transactions:write"
  ],
  "created_at": "2024-03-04T10:30:00Z",
  "expires_at": "2024-12-31T23:59:59Z",
  "last_used_at": null
}

The key field is only returned when creating a new API key. Store it securely - you won’t be able to retrieve it again.

Permission Scopes

Scopes follow the format resource:action.

Available Resources

ledgers - Ledger operations
balances - Balance management
accounts - Account operations
identities - Identity management
transactions - Transaction operations
balance-monitors - Balance monitoring
hooks - Webhook configuration
api-keys - API key management
search - Search operations
reconciliation - Reconciliation operations
metadata - Metadata updates
backup - Database backup operations
* - All resources (wildcard)

Available Actions

read - GET and HEAD requests
write - POST, PUT, PATCH requests
delete - DELETE requests
* - All actions (wildcard)

Scope Examples

[
  "ledgers:read",              // Read-only access to ledgers
  "balances:*",                // Full access to balances
  "transactions:write",        // Create/update transactions only
  "*:read",                    // Read-only access to all resources
  "*:*"                        // Full access to everything
]

HTTP Method Mapping

HTTP Method	Required Action
GET	read
HEAD	read
POST	write
PUT	write
PATCH	write
DELETE	delete

Listing API Keys

Retrieve all API keys for a specific owner.

Endpoint

GET /api-keys?owner={owner_id}

Query Parameters

owner

string

required

Filter API keys by owner identifier

Example Request

curl -X GET "http://localhost:5001/api-keys?owner=mobile-team" \
  -H "X-Blnk-Key: your-master-key"

Response

Returns an array of API key objects (without the key field):

[
  {
    "api_key_id": "key_1234567890abcdef",
    "name": "Mobile App Production",
    "owner": "mobile-team",
    "scopes": ["ledgers:read", "balances:*"],
    "created_at": "2024-03-04T10:30:00Z",
    "expires_at": "2024-12-31T23:59:59Z",
    "last_used_at": "2024-03-04T15:20:00Z"
  }
]

Revoking API Keys

Revoke an API key to permanently disable it.

Endpoint

DELETE /api-keys/{id}?owner={owner_id}

Parameters

string

required

The API key ID to revoke

owner

string

required

Owner identifier (must match the key’s owner)

Example Request

curl -X DELETE "http://localhost:5001/api-keys/key_1234567890abcdef?owner=mobile-team" \
  -H "X-Blnk-Key: your-master-key"

Response

Returns HTTP 204 (No Content) on success.

Error Responses

404

error

API key not found

403

error

Unauthorized - owner doesn’t match

Using API Keys

Once created, use the API key in the X-Blnk-Key header:

curl -X POST http://localhost:5001/transactions \
  -H "X-Blnk-Key: blnk_sk_1234567890abcdefghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "precision": 100,
    "reference": "ref_001",
    "currency": "USD",
    "source": "bln_source",
    "destination": "bln_dest"
  }'

Automatic Metadata Injection

When an API key is used to create resources (POST requests), Blnk automatically adds metadata to track the creator:

{
  "meta_data": {
    "BLNK_GENERATED_BY": "key_1234567890abcdef",
    "custom_field": "your_value"
  }
}

This helps audit which API key created which resources.

Key Expiration and Validation

API keys are validated on every request:

Existence: Key must exist in the database
Expiration: Current time must be before expires_at
Status: Key must not be revoked
Permissions: Key must have appropriate scope for the requested resource and action

Validation Errors

401

error

{"error": "Invalid API key"}

The API key doesn’t exist or is malformed

401

error

{"error": "API key is expired or revoked"}

The API key has expired or been revoked

403

error

{"error": "Insufficient permissions for transactions:write"}

The API key lacks the required scope

Last Used Tracking

Blnk automatically tracks when each API key was last used. The last_used_at timestamp is updated in the background on each successful request.

Best Practices

Use scoped keys: Create API keys with minimal required permissions
Set expiration dates: Use reasonable expiry times for enhanced security
Rotate keys regularly: Create new keys and revoke old ones periodically
Use different keys per service: Don’t share keys across multiple services
Secure key storage: Store keys in environment variables or secure vaults
Monitor usage: Review last_used_at to identify unused keys

Public Endpoints

The following endpoints are publicly accessible without authentication:

GET / - Server health check
GET /health - Health endpoint

All other endpoints require authentication when secure mode is enabled.

Example: Complete Authentication Flow

Step 1: Configure Master Key

export BLNK_SERVER_SECURE=true
export BLNK_SERVER_SECRET_KEY="master_key_12345"

Step 2: Create an API Key

curl -X POST http://localhost:5001/api-keys \
  -H "X-Blnk-Key: master_key_12345" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Service",
    "owner": "analytics-team",
    "scopes": ["transactions:read", "balances:read"],
    "expires_at": "2024-06-30T23:59:59Z"
  }'

Step 3: Use the API Key

curl -X GET http://localhost:5001/transactions \
  -H "X-Blnk-Key: blnk_sk_returned_from_step_2"

Step 4: Revoke When Done

curl -X DELETE "http://localhost:5001/api-keys/key_id?owner=analytics-team" \
  -H "X-Blnk-Key: master_key_12345"

Overview

Ledgers

Balances

Balance Monitors

Transactions

Identities

Accounts

Reconciliation

Search

Webhooks

API Keys

Metadata

Backup

​Overview

​Authentication Header

​Secure Mode

​Authentication Types

​Master Key

​API Keys

​Key Features:

​Creating API Keys

​Endpoint

​Request Body

​Example Request

​Response

​Permission Scopes

​Available Resources

​Available Actions

​Scope Examples

​HTTP Method Mapping

​Listing API Keys

​Endpoint

​Query Parameters

​Example Request

​Response

​Revoking API Keys

​Endpoint

​Parameters

​Example Request

​Response

​Error Responses

​Using API Keys

​Automatic Metadata Injection

​Key Expiration and Validation

​Validation Errors

​Last Used Tracking

​Best Practices

​Public Endpoints

​Example: Complete Authentication Flow

​Step 1: Configure Master Key

​Step 2: Create an API Key

​Step 3: Use the API Key

​Step 4: Revoke When Done

Build docs developers (and LLMs) love

Overview

Authentication Header

Secure Mode

Authentication Types

Master Key

API Keys

Key Features:

Creating API Keys

Endpoint

Request Body

Example Request

Response

Permission Scopes

Available Resources

Available Actions

Scope Examples

HTTP Method Mapping

Listing API Keys

Endpoint

Query Parameters

Example Request

Response

Revoking API Keys

Endpoint

Parameters

Example Request

Response

Error Responses

Using API Keys

Automatic Metadata Injection

Key Expiration and Validation

Validation Errors

Last Used Tracking

Best Practices

Public Endpoints

Example: Complete Authentication Flow

Step 1: Configure Master Key

Step 2: Create an API Key

Step 3: Use the API Key

Step 4: Revoke When Done