Endpoint
Creates a new API key for authenticating with the Blnk API. API keys can have specific scopes and expiration dates.
Request Body
A descriptive name for the API key to help identify its purpose
The identifier of the owner or user this API key belongs to
Array of permission scopes this API key should have. Determines what operations the key can performCommon scopes:
transactions:read: Read transaction datatransactions:write: Create and modify transactionsbalances:read: Read balance informationbalances:write: Modify balancesledgers:read: Read ledger dataledgers:write: Create and modify ledgersadmin: Full administrative access
Expiration date for the API key (ISO 8601 format). After this date, the key will no longer be valid
Response
Unique identifier for the API key
The actual API key string. This is only shown once during creation - store it securely!
The descriptive name of the API key
The identifier of the owner
Array of permission scopes
Expiration date (ISO 8601 format)
Timestamp when the API key was created
Timestamp of last use (initially same as created_at)
Whether the key has been revoked
Example Request
Production API Key
{
"name": "Production Server Key",
"owner": "user_123abc",
"scopes": [
"transactions:read",
"transactions:write",
"balances:read"
],
"expires_at": "2025-12-31T23:59:59Z"
}
Read-Only API Key
{
"name": "Analytics Dashboard - Read Only",
"owner": "user_456def",
"scopes": [
"transactions:read",
"balances:read",
"ledgers:read"
],
"expires_at": "2024-12-31T23:59:59Z"
}
Admin API Key
{
"name": "Admin Console",
"owner": "admin_789ghi",
"scopes": ["admin"],
"expires_at": "2024-06-30T23:59:59Z"
}
Short-lived Testing Key
{
"name": "Integration Test",
"owner": "test_user",
"scopes": ["transactions:write", "balances:read"],
"expires_at": "2024-03-11T23:59:59Z"
}
Example Response
{
"api_key_id": "api_key_abc123def456",
"key": "blnk_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"name": "Production Server Key",
"owner_id": "user_123abc",
"scopes": [
"transactions:read",
"transactions:write",
"balances:read"
],
"expires_at": "2025-12-31T23:59:59Z",
"created_at": "2024-03-04T12:00:00Z",
"last_used_at": "2024-03-04T12:00:00Z",
"is_revoked": false
}
Error Responses
Error message describing what went wrong
Common Errors
- 400 Bad Request: Invalid request body or missing required fields
- 500 Internal Server Error: Failed to create API key
Security Best Practices
Store the Key Securely
The key field is only returned during creation. You must store it securely:
// DO: Store in environment variables
process.env.BLNK_API_KEY = apiKeyResponse.key;
// DO: Store in secrets manager
await secretsManager.storeSecret('blnk-api-key', apiKeyResponse.key);
// DON'T: Store in code or version control
const apiKey = 'blnk_live_sk_...'; // Never do this!
Use Principle of Least Privilege
Grant only the scopes needed:
// Good: Specific scopes for specific use case
{
name: "Payment Processor",
scopes: ["transactions:write", "balances:read"]
}
// Bad: Overly broad permissions
{
name: "Payment Processor",
scopes: ["admin"] // Too much access!
}
Set Appropriate Expiration
Choose expiration dates based on key usage:
// Production keys: 1 year
expires_at: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
// Development keys: 90 days
expires_at: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString()
// Testing keys: 7 days
expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
Rotate Keys Regularly
Implement key rotation:
const rotateApiKey = async (oldKeyId, owner, scopes) => {
// Create new key
const newKey = await createApiKey({
name: `Rotated Key - ${new Date().toISOString()}`,
owner,
scopes,
expires_at: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
});
// Update your systems to use new key
await updateSystemConfig(newKey.key);
// Revoke old key
await revokeApiKey(oldKeyId);
return newKey;
};
Scope Definitions
Read Scopes
transactions:read: View transaction history and detailsbalances:read: View balance informationledgers:read: View ledger dataidentities:read: View identity informationreconciliations:read: View reconciliation status
Write Scopes
transactions:write: Create and modify transactionsbalances:write: Modify balance recordsledgers:write: Create and modify ledgersidentities:write: Create and modify identitiesreconciliations:write: Start and manage reconciliations
Special Scopes
admin: Full administrative access to all resourceswebhooks:manage: Create, update, and delete webhooksapi_keys:manage: Manage API keys
API Key Naming Conventions
Use descriptive names that indicate:
- Environment (production, staging, development)
- Purpose (payment processing, analytics, admin)
- Owner or system (user name, service name)
Examples:
- “Production - Payment Service”
- “Staging - Analytics Dashboard”
- “Development - John’s Test Key”
- “Admin - Billing System”
Using the API Key
Include the API key in the Authorization header:
curl -X GET "https://api.blnk.io/accounts" \
-H "Authorization: Bearer blnk_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
fetch('https://api.blnk.io/accounts', {
headers: {
'Authorization': 'Bearer blnk_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
}
});
