Authentication

Obtain and use an API Key

Obtain an API Key through the official console, selecting the minimum permissions required. Node management requests use:

Authorization: Bearer <API_KEY>
X-Network: regtest

X-Network must be regtest, testnet or mainnet, matching the key and target resource. Do not infer the network from the API base URL alone.

Scopes

• nodes:read: query node lists and node details.
• nodes:write: create, start, stop and delete nodes, and allocate P2P addresses. There is no separate deletion scope.

API Keys do not grant node runtime access; use the official product for export and LSP keep-alive protection.

Secure storage

• Keep keys in a backend or secure server-side secret store, not in browsers, mobile apps or public repositories.
• Do not place keys in source code, URLs, logs or error reports. Send requests over HTTPS.
• Separate keys by environment and purpose. Revoke and replace a compromised key through the official console.

Request UUIDs and retries

Node creation, start, stop and deletion accept optional Request-Id or X-Request-Id. A nonzero UUID is recommended. If both headers are supplied, they must match; invalid, zero or conflicting UUIDs return 400. The server generates a UUID if omitted.

Save and reuse the same UUID when retrying the same request; use different UUIDs for different operations or requests. Responses include X-Request-Id, and idempotency cache hits also include X-Idempotent-Cached: true. Do not generalize this behavior to all write endpoints: P2P allocation is repeatable but does not use this idempotency cache.

Error handling

Management API JSON errors contain code, message and request_id, for example:

{
  "code": "bad_request",
  "message": "Invalid request",
  "request_id": "d9ae2a18-4279-4c4d-b584-8ef35295b548"
}

Common HTTP statuses and error codes:

• 400 bad_request: invalid request, including unsupported creation fields or an invalid request UUID.
• 401 unauthorized: authentication failed.
• 403 forbidden: insufficient permissions or access denied.
• 404 not_found: the target node does not exist or is outside the current user/network scope.
• 409 conflict: node state or idempotent request conflict.
• 422 validation_failed: the request format does not meet requirements.
• 429 rate_limited: follow the response's Retry-After before retrying.
• 5xx internal_error: service or dependency unavailable; see each operation for specific statuses.

message may be localized using Accept-Language; do not branch on its exact text. Retain request_id for troubleshooting, but do not log authorization headers or other secrets.