# NordBastion: API and MCP

## Create and test a key before paying

1. POST https://nordbastion.com/v1/auth/register with email + password.
   Or POST /v1/auth/login. For 2FA, include totp_code with email + password.
2. Read response.tokens.access_token (nb_at_*).
3. POST /v1/auth/api-keys with Authorization: Bearer <access_token> and
   {"name":"agent-read","scope":"read"}.
4. Store response.plaintext in a secret store. It is shown once; only its hash is stored.
5. GET /v1/account/balance with the new key to test before making any deposit.

No payment or manual activation required. Up to 10 active keys per account.
Scopes: read, billing, servers, full. Only full can create/revoke API keys.
DELETE /v1/auth/api-keys/{key_id} revokes a key immediately.

## MCP

Endpoint: https://nordbastion.com/mcp (POST, Streamable HTTP with JSON responses).
Protocol 2026-07-28: server/discover; required per-request _meta and routing headers.
Legacy initialize: 2025-11-25, 2025-06-18, 2025-03-26.
Server release: 1.1.0. Stdio release: 0.2.0, official MCP Python SDK 2.2.0.

Public tools include list_vps, list_bastions and register_account. To bootstrap:
register_account -> tokens.access_token -> create_api_key(name,scope,access_token).
Protected tools accept an Authorization Bearer header or an access_token argument.
Identity is verified on every request; signup does not authenticate later calls implicitly.
Browser OAuth authorization-code/PKCE login is not implemented. Use Bearer credentials.
The server-card is supplemental metadata, not an MCP endpoint or an A2A service.

## SSH keys

Generate the SSH key pair on the client. Send only the public key to add_ssh_key
or POST /v1/ssh-keys. Never upload the SSH private key.

## Payment

Creating keys, reading the catalog and checking balance are free.
POST /v1/billing/topups uses {"amount_usd":50,"crypto":"XMR"}, not coin.
Allowed USD amount: 30 to 10000. GET /v1/billing/coins lists available codes.
Creating an invoice does not transfer funds; the wallet owner must authorize payment.
x402 is the signed USDC-on-Base top-up flow at /v1/billing/topups:
use X-Payment-Mode: x402, then the signed X-PAYMENT payload for settlement.
Wait for confirmed credit before ordering. Receipt strings do not pay for server orders.

## Limits and current scope

API keys: 120 requests/min, 3000/hour. Anonymous: 30/min. HTTP 429 includes Retry-After.
API activity is audited; credentials and request bodies are excluded from the audit log.
SDKs for Python/TypeScript/Go/Rust and the nb CLI remain planned; use HTTP or MCP.
Snapshots, networking and storage APIs remain planned. Account PATCH has no mutable fields.

## References

- Working examples and downloads: https://nordbastion.com/agents/
- Endpoint reference: https://nordbastion.com/api/
- OpenAPI: https://nordbastion.com/.well-known/openapi.json
- MCP metadata: https://nordbastion.com/.well-known/mcp/server-card.json
- Versioned source and checksums: https://nordbastion.com/agents/#downloads
- Privacy and terms: https://nordbastion.com/doctrine/