Endpoints, payloads, and tokens.

The API holds network records, queues maintenance jobs, mints tokens, and emits audit events. All state-changing routes require a bearer token and a role at least equal to operator; admin-only routes require admin.

Authentication

Pass Authorization: Bearer <token> on every request. In local development, BAAS_ADMIN_BOOTSTRAP_TOKEN grants admin access for the tenant_dev tenant.

curl -s http://localhost:4100/v1/plans \
  -H "Authorization: Bearer dev-admin-token-change-me"

Endpoints

GET/healthLiveness probe for the BaaS API.
GET/v1/plansList launch plans available to the caller.
GET/v1/deployment/targetsList supported deployment targets and lifecycle actions.
GET/v1/maintenance/actionsList allowlisted maintenance action definitions.
GET/v1/tenantsList tenants visible to the caller.
GET/v1/networksList networks for the signed-in tenant.
POST/v1/networksCreate a network record from the portal or an integration.
GET/v1/networks/:networkIdRead a single network record.
POST/v1/networks/:networkId/maintenance/jobsEnqueue a supported maintenance action.
GET/v1/maintenance/jobs/:jobIdRead job status and worker result.
POST/v1/wallets/generateQueue a wallet-generation job through the worker.
POST/v1/api-tokensIssue a scoped, hashed-at-rest API token.

Create network

Idempotent in spirit: a fresh POST always returns a new net_… record. An audit event network.create is written for every successful call.

POST /v1/networks
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "partner-testnet",
  "plan": "resilient_7",
  "environment": "testnet",
  "resource_profile": "lab",
  "deployment_target": "local_fs",
  "consensus_mode": "private",
  "chain_id": "nabd-partner-testnet",
  "token_symbol": "NABD",
  "token_name": "NABD Token",
  "token_decimals": 6,
  "initial_supply": "5000000000000",
  "treasury_address": "NABD_TREASURY_001"
}

Network creation validates all profile fields. initial_supply must be an integer string in base units and must not exceed 9223372036854775807, the signed 64-bit boundary used by ledger storage paths.

Generate wallet

Wallet generation queues an audited worker job. By default, the job returns address, public key, and local secret path, not the private key.

POST /v1/wallets/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "network_id": "net_...",
  "label": "nabd-partner-testnet-treasury",
  "purpose": "treasury",
  "expose_private_key_once": false
}

Queue a maintenance job

The action must be in the allowlist maintenance.health ... wallet.generate or the API returns 400 unsupported_action.

POST /v1/networks/:networkId/maintenance/jobs
Authorization: Bearer <token>

{
  "action": "maintenance.restart-node",
  "target_node": "nabd-validator-3",
  "confirmation": "restart nabd-validator-3"
}

// 202 Accepted
{ "operation_id": "job_…", "status": "queued" }

Job lifecycle

  • queued → worker has not claimed yet
  • running → worker holds the lock
  • completed → result stored in result_json
  • failed → worker error stored in error
  • blocked → the canonical NABD CLI refused the operation (dangerous path)
Every API write produces an audit event. Treat audit as a primary integration surface, not a side effect.