The NordBastion polar-bear mascot seated at a tactical mission-control workstation with floating holographic terminal monitors showing cyan code, a mechanical keyboard with cyan-lit keycaps and the cyan-N shield leaning beside him, inside an exposed Nordic stone console room with an aurora-lit window

API.v1 · REST · 70+ endpoints · 5 SDKs

Run NordBastion from code.
KYC-free, crypto-paid, fully scriptable.

Provision servers, take snapshots, top up in cryptocurrency, run ping from any bastion. Every panel action has a REST endpoint and four SDKs. Same identity floor as the panel: an email and a password, nothing more.

Quick start All endpoints

Version: v1
Endpoints: 70+
SDKs: 4 + CLI
Bastions: 4 Nordic
Rate limit: 1000/min read
KYC: None

Quick start

Three steps from a signed-up account to a booted server in code.

01 Create an account

POST /v1/auth/register

Email + password, no KYC. Returns a 24-hour access token straight away — no email confirmation step.

curl -sS https://nordbastion.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"••••••••••••"}'

02 Top up in crypto

POST /v1/billing/topups

Open a per-coin invoice. The response carries a deposit address, QR code and expiry timestamp.

amount_usd must be between $30 and $10,000 (server-enforced). Lower returns HTTP 422 amount_too_low, higher returns amount_too_high.

curl -sS https://nordbastion.com/v1/billing/topups \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":50,"coin":"xmr"}'

03 Provision a server

POST /v1/servers

Pick a tier (service_code), a bastion and an image. Server is booted with SSH in about ninety seconds.

curl -sS https://nordbastion.com/v1/servers \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"service_code":"NB-V3","bastion":"STO","image":"debian-12"}'

SDKs & CLI

Four languages, one binary.

Each SDK is MIT-licensed, source-available, semver-stable from v1.0. All share the same authenticated client interface — list servers, in any language.

Planned for v1.1

These SDKs are planned for v1.1. The REST API at /v1/* is fully usable from any HTTP client today — see the agents page for cURL and MCP examples.

Python

pip

pip install nordbastion

from nordbastion import Client
nb = Client(api_key="nb_live_••••")

for s in nb.servers.list():
    print(s.id, s.name, s.status)

TypeScript

npm

npm i @nordbastion/api

import { NordBastion } from '@nordbastion/api';
const nb = new NordBastion({ apiKey: 'nb_live_••••' });

const servers = await nb.servers.list();
servers.forEach(s => console.log(s.id, s.name, s.status));

Go

go install

go get go.nordbastion.com/api

import nb "go.nordbastion.com/api"

c := nb.New(nb.WithAPIKey("nb_live_••••"))
servers, _ := c.Servers.List(ctx)
for _, s := range servers {
    fmt.Println(s.ID, s.Name, s.Status)
}

Rust

cargo

cargo add nordbastion

use nordbastion::Client;
let nb = Client::builder()
    .api_key("nb_live_••••").build()?;

for s in nb.servers().list().await? {
    println!("{} {} {}", s.id, s.name, s.status);
}

CLI · nb

Planned for v1.1

curl -sSL https://get.nordbastion.com | sh

nb auth login --api-key nb_live_••••
nb servers list
nb servers create --tier NB-V3 --bastion STO
nb servers snap NB-srv-1234 --name pre-upgrade

Curl-first

The REST API works with any HTTP client. JSON request and response bodies, JWT bearer or scoped API key, signed webhook payloads. No SDK lock-in.

curl -H "Authorization: Bearer nb_live_••••" https://nordbastion.com/v1/servers

Endpoint reference

70+ endpoints across twelve resource groups.

Authentication · 14 endpoints

POST	/v1/auth/register LIVE	Create a NordBastion account from email + password (no KYC).
POST	/v1/auth/login LIVE	Exchange email + password for a bearer token. Returns 24-hour JWT.
POST	/v1/auth/login/totp LIVE	Second step when the account has TOTP 2FA enabled.
POST	/v1/auth/token/refresh LIVE	Rotate a bearer token without re-entering credentials.
POST	/v1/auth/recover LIVE	Initiate account recovery (PGP-based, stubbed in v1.0).
GET	/v1/auth/sessions LIVE	List active sessions for the current account.
DELETE	/v1/auth/sessions/{token_id} LIVE	Revoke a session by token ID (logout-everywhere).
POST	/v1/auth/totp/setup LIVE	Begin TOTP enrollment — returns the provisioning URI.
POST	/v1/auth/totp/enable LIVE	Confirm a TOTP code and enable 2FA.
POST	/v1/auth/totp/disable LIVE	Disable 2FA with a current TOTP code.
POST	/v1/auth/password LIVE	Change the account password.
POST	/v1/auth/api-keys LIVE	Create a scoped, long-lived API key (read · billing · servers · full).
GET	/v1/auth/api-keys LIVE	List API keys for the current account (last-used + scopes).
DELETE	/v1/auth/api-keys/{key_id} LIVE	Revoke an API key immediately.

Account · 5 endpoints

GET	/v1/account LIVE	Get the authenticated account (email, status, locale, 2FA state).
PATCH	/v1/account LIVE	Update email, password, locale, default bastion preference.
GET	/v1/account/balance LIVE	Current prepaid balance in USD.
GET	/v1/account/usage LIVE	Trailing-30-day API usage totals.
GET	/v1/account/audit-log LIVE	Recent authenticated requests for this account.

Billing & crypto top-ups · 8 endpoints

POST	/v1/billing/topups LIVE	Create a top-up intent. Returns a per-coin address + QR + expiry.
GET	/v1/billing/topups LIVE	List pending and confirmed crypto top-ups.
GET	/v1/billing/topups/{order_number} LIVE	Status of a single top-up (confirmations, settle status).
POST	/v1/billing/topups/{order_number}/cancel LIVE	Cancel a still-open top-up.
GET	/v1/billing/bonus-tiers LIVE	Public top-up bonus tier ladder.
GET	/v1/billing/coins LIVE	12 supported cryptocurrencies + current settle threshold per coin.
GET	/v1/billing/invoices PLANNED	List invoices (monthly statements).	roadmap
GET	/v1/billing/invoices/{id} PLANNED	Single invoice. Format: JSON · PDF · PGP-signed PDF.	roadmap

Catalogue · 7 endpoints

GET	/v1/catalog LIVE	Bundle of all catalog resources in one call.
GET	/v1/catalog/vps LIVE	Five VPS tiers — Sentinel · Garrison · Ravelin · Bulwark · Citadel.
GET	/v1/catalog/dedicated LIVE	Five dedicated tiers — Bastion-Lite to Bastion-Hyperion.
GET	/v1/catalog/bastions LIVE	Four Nordic bastions — STO · HEL · OSL · RKV with live status.
GET	/v1/catalog/images LIVE	Default OS images — Debian · Ubuntu · Alpine · Arch · FreeBSD · Win.
GET	/v1/catalog/{code} LIVE	Lookup a single tier by service_code.
GET	/v1/catalog/iso PLANNED	Library of bootable ISO images for custom installs.	roadmap

Servers · 14 endpoints

POST	/v1/servers LIVE	Provision a new VPS or dedicated server. Returns 202 + order_number.
GET	/v1/servers LIVE	List servers — supports filter, sort, paginate, field selection.
GET	/v1/servers/{order_number} LIVE	Single server with full configuration + current status.
PATCH	/v1/servers/{order_number} LIVE	Mutate a server (hostname only in v1.0).
DELETE	/v1/servers/{order_number} LIVE	Cancel / decommission a server. Pro-rated credit returned.
POST	/v1/servers/{id}/power PLANNED	Start · stop · restart · poweroff · acpi-shutdown.	roadmap
POST	/v1/servers/{id}/reinstall PLANNED	Reinstall OS from any catalogue image or custom template.	roadmap
POST	/v1/servers/{id}/rescue PLANNED	Reboot into rescue mode (Alpine ramdisk · 1 hour timeout).	roadmap
POST	/v1/servers/{id}/resize PLANNED	Move a VPS up or down between tiers. Applies on next reboot.	roadmap
POST	/v1/servers/{id}/migrate PLANNED	Redeploy a snapshot to another bastion. Pin to STO · HEL · OSL · RKV.	roadmap
POST	/v1/servers/{id}/password-reset PLANNED	Reset root password. Returned once, never stored.	roadmap
GET	/v1/servers/{id}/metrics PLANNED	Per-minute CPU · RAM · disk · network for the last 90 days.	roadmap
GET	/v1/servers/{id}/console PLANNED	One-time URL to the web VNC/SPICE console (expires 5 min).	roadmap
GET	/v1/servers/{id}/serial PLANNED	One-time URL to the web serial console (expires 5 min).	roadmap

Snapshots · 5 endpoints

POST	/v1/servers/{id}/snapshots PLANNED	Create a live or quiesced snapshot (off-host, encrypted).	roadmap
GET	/v1/servers/{id}/snapshots PLANNED	List snapshots for a server (size, age, source).	roadmap
POST	/v1/servers/{id}/snapshots/{snapId}/restore PLANNED	Restore in place — server reboots into the snapshot.	roadmap
DELETE	/v1/servers/{id}/snapshots/{snapId} PLANNED	Delete a snapshot.	roadmap
POST	/v1/servers/{id}/snapshots/{snapId}/export PLANNED	Export a snapshot as a .qcow2 download. PGP-signed manifest.	roadmap

SSH keys · 4 endpoints

POST	/v1/ssh-keys LIVE	Register a new SSH public key. SHA-256 fingerprint indexed.
GET	/v1/ssh-keys LIVE	List SSH keys on the account.
GET	/v1/ssh-keys/{id} LIVE	A single SSH public key.
DELETE	/v1/ssh-keys/{id} LIVE	Remove a key (does not change any existing server's installed keys).

Networking · 8 endpoints

GET	/v1/networking/ips PLANNED	List IPv4 + IPv6 addresses assigned to your servers.	roadmap
POST	/v1/networking/ips/floating PLANNED	Request additional IPv4 or a /64 IPv6 block. Bastion-scoped.	roadmap
POST	/v1/networking/rdns PLANNED	Set reverse-DNS PTR. IPv4 + IPv6 supported.	roadmap
POST	/v1/networking/firewall PLANNED	Create or replace a firewall ruleset for one or more servers.	roadmap
GET	/v1/networking/firewall PLANNED	List firewall rulesets and their bindings.	roadmap
POST	/v1/networking/private-network PLANNED	Create a VPC-style private network between your own servers.	roadmap
POST	/v1/networking/byoip PLANNED	Announce your own /24 (IPv4) or /48 (IPv6). RPKI-verified.	roadmap
POST	/v1/networking/lookingglass PLANNED	Run ping · traceroute · MTR from any of the four bastions.	roadmap

Storage · 5 endpoints

POST	/v1/storage/volumes PLANNED	Provision an additional NVMe volume — 10 GB to 16 TB, bastion-scoped.	roadmap
GET	/v1/storage/volumes PLANNED	List volumes on the account.	roadmap
POST	/v1/storage/volumes/{id}/attach PLANNED	Attach a volume to a running or stopped server.	roadmap
POST	/v1/storage/volumes/{id}/detach PLANNED	Detach a volume (requires the server to be stopped).	roadmap
POST	/v1/storage/volumes/{id}/resize PLANNED	Grow a volume. Shrink not supported.	roadmap

Images & templates · 3 endpoints

POST	/v1/images/iso/upload PLANNED	Upload a custom .iso (≤ 4 GB) bootable from any server's rescue path.	roadmap
POST	/v1/images/templates PLANNED	Register a custom OS template from an existing snapshot.	roadmap
GET	/v1/images/templates PLANNED	List your custom templates.	roadmap

Webhooks · 4 endpoints

POST	/v1/webhooks LIVE	Subscribe a URL to one or more event types. HMAC-signed payloads.
GET	/v1/webhooks LIVE	List webhook subscriptions on the account.
DELETE	/v1/webhooks/{id} LIVE	Remove a webhook subscription.
POST	/v1/webhooks/{id}/test LIVE	Send a synthetic test event to a webhook URL.

Transparency · 4 endpoints

GET	/v1/transparency/canary LIVE	Current warrant canary, PGP-signed payload. Same content as /warrant-canary/.
GET	/v1/transparency/peering LIVE	AS213232 peering announcements + current prefix list.
GET	/v1/transparency/status LIVE	Live operational status of every bastion + shared services.
GET	/v1/transparency/incidents PLANNED	Operational incidents (last 12 months, rolling).	roadmap

Agents directory · 2 endpoints

GET	/v1/agents/directory LIVE	Public listing of agents using NordBastion.
POST	/v1/agents/directory LIVE	Submit this account's agent for the public directory.

OAuth 2.1 / DCR · 4 endpoints

POST	/v1/oauth/register LIVE	RFC 7591 Dynamic Client Registration.
POST	/v1/oauth/token LIVE	Token endpoint — client_credentials, password, refresh_token.
POST	/v1/oauth/revoke LIVE	Revoke an access or refresh token.
GET	/v1/oauth/introspect LIVE	Introspect a token (RFC 7662, basic info only).

All endpoints follow JSON in / JSON out, pagination by ?page= & ?per_page=, filtering by ?filter[field]= and field selection by ?fields=. Every request can carry an Idempotency-Key header.

Authentication

Three credential kinds, two privacy modes.

Bearer token LIVE

Email + password · JWT · 24-hour expiry

Short-lived JWT issued by POST /v1/auth/login. Carries scope claims and a session-revocation ID. Refreshable for 30 days via /v1/auth/token/refresh.

Authorization: Bearer eyJhbGciOi••••

Scoped API key LIVE

Long-lived · scoped · revocable

Scopes: read-only, billing-read, billing-write, servers-read, servers-write, full. Optional IP allowlist (CIDR), optional expiry. Recommended for CI and infrastructure scripts.

Authorization: Bearer nb_live_3f9c2a••••

Mutual TLS Planned v1.1

Client certificate · enterprise / compliance

Pin an mTLS client certificate to an API key. Requests that present the wrong client certificate are rejected at the TLS layer before any application logic runs. Available on request via the panel.

curl --cert client.pem --key client.key https://nordbastion.com/v1/servers

PGP-signed responses Planned v1.1

Opt-in detached signature · verifiable offline

Set X-NB-Sign: 1 on any request. The response body is wrapped in a detached PGP cleartext signature using the NordBastion key (fingerprint at /pgp/). Used by compliance pipelines that mistrust the TLS chain alone.

curl -H "X-NB-Sign: 1" -H "Authorization: Bearer ..." https://nordbastion.com/v1/transparency/canary

NordBastion does not collect identity at signup, and the API does not change that floor. There is no SMS verification webhook, no email-confirmation flow, no identity-document upload endpoint. The API exposes money, machines and metadata — that is the whole surface area.

Rate limits

Per-key, published per-minute

Read endpoints: 1000 / min
Write endpoints: 100 / min
Auth-sensitive: 10 / min
429 retry: Retry-After

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Higher tiers are available on request from the panel.

Versioning

Twelve-month deprecation floor

Endpoints are URL-versioned under /v1/. Breaking changes only ship in a new major version. The previous major remains supported for at least twelve months. Deprecated endpoints carry Sunset and Deprecation response headers.

Sunset: Wed, 01 Jul 2027 00:00:00 GMT
Deprecation: true

Error format

Stable envelope, machine-readable code

{
  "error": {
    "type":    "invalid_request",
    "code":    "invalid_bastion",
    "message": "Unknown bastion 'mxp'.",
    "request_id": "req_2VqK8e...",
    "doc_url": "https://nordbastion.com/api/#errors"
  }
}

Webhooks

Signed events, retried with backoff.

Every event payload is HMAC-signed with your webhook secret. Three retry attempts with exponential backoff over an hour, then dropped. Test deliveries available from POST /v1/webhooks/{id}/test.

account.balance.low

Balance dropped below the configured threshold.

topup.created

Crypto top-up address generated, waiting for first confirmation.

topup.confirmed

Top-up settled on-chain. Balance credited.

topup.failed

Top-up address expired without confirmation.

invoice.issued

Monthly invoice issued. PDF + PGP-signed PDF available.

server.provisioning

Provisioning started — image being written.

server.provisioned

Server is booted and reachable on SSH.

server.power.on

Server powered on (manual or scheduled).

server.power.off

Server powered off (manual or scheduled).

server.reinstalled

OS reinstalled. Root password rotated.

server.resized

VPS tier changed. Applied on the next reboot.

server.migrated

Server moved to another bastion via snapshot redeploy.

server.deleted

Server terminated. Pro-rated credit returned.

snapshot.created

Snapshot completed and is downloadable.

snapshot.restored

Snapshot restored in place.

snapshot.deleted

Snapshot removed.

volume.attached

Block volume attached to a server.

volume.detached

Block volume detached.

firewall.changed

Firewall ruleset applied to one or more servers.

canary.updated

Warrant canary reaffirmed (first of every month).

incident.opened

Operational incident opened on a bastion or shared service.

incident.resolved

Operational incident closed.

peering.changed

AS213232 peering or prefix announcement updated.

Transparency endpoints

Programmatic access to the canary, the incident log, the peering record.

Most cloud APIs expose products and billing. NordBastion also exposes its own transparency surface — programmatically. The same warrant canary that is published at /warrant-canary/ is available as a signed JSON payload at /v1/transparency/canary. The same incident history that drives /status/ is at /v1/transparency/incidents. The same peering record that lives on /peering/ is at /v1/transparency/peering. The same AS213232 prefix announcements are queryable in real time.

Subscribe to the canary.updated webhook and you get a push notification the first day of every month — if it stops firing, the canary is broken, and you know without polling. Build the alert yourself, in your own infrastructure, with the cryptographic signature you can verify offline against the published PGP key.

This is the part of the API that no commercial cloud has, because no commercial cloud has the doctrine to back it.

Sample · GET /v1/transparency/canary

{
  "as_of": "2026-05-01T00:00:00Z",
  "statement": "NordBastion has received no...",
  "signature": "-----BEGIN PGP SIGNATURE-----...",
  "key_fingerprint": "B9BB 3413 6FDC C3DA 8356 50C8 1A32 1442 3855 B282",
  "next_reaffirmation": "2026-06-01T00:00:00Z"
}

Read the canary page Read the transparency report The PGP key

FAQ · API

Developer questions, answered.

The questions a developer asks before committing infrastructure to a host's API.

Is there really an API and is it KYC-free?

Yes — every action you can take in the control panel has an API equivalent today or on the published roadmap, and the API itself is gated by the same authenticated panel account: an email and a password. No identity verification is required to obtain or use API credentials.

Which programming languages have official SDKs?

Four official SDKs and one CLI. Python (pip install nordbastion), TypeScript / Node (npm install @nordbastion/api), Go (go install go.nordbastion.com/cli/nb@latest), Rust (cargo add nordbastion) and a single-binary cross-platform CLI (nb) installable via curl. All SDKs are MIT-licensed and source-available.

Can I top up my balance from code, in cryptocurrency?

Yes. POST /v1/billing/topups creates a top-up intent and returns a per-coin destination address, QR code and expiry timestamp. When the network confirms the payment, your prepaid balance is credited automatically and a topup.confirmed webhook fires. Twelve cryptocurrencies are supported, listed at /v1/billing/coins.

Are the API endpoints reachable over Tor?

The clearnet endpoint api.nordbastion.com is Tor-friendly today with no special-case rate limits or anti-Tor blocking. A v3 onion mirror of the API surface is on the panel roadmap and will share the same TLS-certified material via Onion-Location response headers when it ships.

What does "PGP-signed responses" mean?

You can opt your API key into PGP-signed response bodies. Each JSON response is wrapped in a detached cleartext PGP signature using the NordBastion key (fingerprint at /pgp/). The wrapping is verifiable offline and is useful for compliance and source-attestation in environments that mistrust the TLS chain alone.

How are rate limits enforced?

Per API key. The published baseline is 1000 read requests per minute and 100 write requests per minute, plus 10 requests per minute on auth-sensitive endpoints (login, password reset, key creation). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; 429 responses include a Retry-After header. Verified developer accounts can request higher tiers from the panel.

How does versioning work?

Endpoints are URL-versioned under /v1/. Breaking changes only ship in a new major version (/v2/, /v3/) and the previous major remains supported for at least twelve months after the next is released. Deprecated endpoints carry a Sunset header with the cut-off date and a Deprecation: true header on every response.

Why is audit-log opt-in?

Because the NordBastion doctrine says we log only what we must. Operational request metrics live for the rolling window the rate-limiter needs and then expire; a per-customer audit log of API actions is more data than we need to run the platform, so it is off by default. Customers who want it can enable /v1/account/audit-log; once enabled it covers panel + API equally and can be exported.

Ready to script it

Get an API key from the panel.

Same email-and-password floor as the panel. No identity check. Pay in crypto. Boot a Stockholm, Helsinki, Oslo or Reykjavík server in about ninety seconds.

Get API key See VPS catalogue Read the doctrine

Base URL · https://nordbastion.com/v1/ · Status · live operational status · Looking glass · run ping/MTR live