API reference
Create API key
Issue a server key. Secret shown once.
POST
/api-keysIssue a key. The secret is shown once and stored only as a SHA-256 digest.
- Permission
- write:keys
- Auth
- console
- Idempotent
- Yes — send Idempotency-Key
- Language
- Node.js
| Field | In | Type | Required | Description |
|---|---|---|---|---|
| name | body | string | Yes | Label shown in the console. |
| environment | body | string | Yes | sandbox or production. Sandbox keys only create Sepolia invoices and only see sandbox data. |
| type | body | string | No | secret (every permission, server only), restricted (listed permissions, server only) or publishable (browser-safe: networks and realtime tokens only). |
| permissions | body | string[] | No | read:invoices, write:invoices, read:events, read:webhooks, write:webhooks, read:settlement, write:settlement, read:keys, write:keys, read:networks, read:currencies, write:realtime. |
Console-only: needs a signed-in organization admin. API keys are rejected.
const response = await fetch(`${process.env.BOSPAY_API_BASE}/api-keys`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"Authorization": "Bearer CONSOLE_ACCESS_TOKEN",
},
body: JSON.stringify({
"name": "Checkout server",
"environment": "sandbox",
"type": "restricted",
"permissions": [
"read:invoices",
"write:invoices",
"read:events"
]
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Success
201
{
"id": "key_example",
"object": "api_key",
"key": "bospay_rk_sandbox_… (returned once)",
"keyType": "restricted",
"environment": "sandbox",
"permissions": [
"read:invoices",
"write:invoices",
"read:events"
]
}Validation error
400
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}