La mascotte orso polare di NordBastion seduta a una postazione di controllo missione tattica con monitor terminali olografici fluttuanti che mostrano codice ciano, una tastiera meccanica con tasti retroilluminati ciano e lo scudo-N ciano appoggiato accanto a lui, all'interno di una sala console nordica in pietra a vista con una finestra illuminata dall'aurora

API.v1 · REST · 70+ endpoint · 5 SDK

Esegua NordBastion dal codice.
KYC-free, pagato in crypto, completamente scriptabile.

Fare il provisioning di server, prendere snapshot, ricaricare in criptovaluta, eseguire ping da qualsiasi bastione. Ogni azione del pannello ha un endpoint REST e quattro SDK. Stesso livello minimo di identità del pannello: un'email e una password, nient'altro.

Avvio rapido Tutti gli endpoint

Versione: v1
Endpoint: 70+
SDK: 4 + CLI
Bastioni: 4 Nordic
Limite di frequenza: 1000/min read
KYC: Nessuno

Avvio rapido

Tre passaggi da un account registrato a un server avviato via codice.

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 Ricarichi in cripto

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 Fare il provisioning di un 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"}'

SDK & CLI

Quattro linguaggi, un binario.

Ogni SDK è con licenza MIT, disponibile come sorgente, stabile per semver dalla v1.0. Tutti condividono la stessa interfaccia client autenticata — elencare server, in qualsiasi linguaggio.

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

L'API REST funziona con qualsiasi client HTTP. Corpo delle richieste e risposte JSON, JWT bearer o chiave API con ambito, payload webhook firmati. Nessun lock-in SDK.

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

Riferimento endpoint

Oltre 70 endpoint su dodici gruppi di risorse.

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).

Tutti gli endpoint seguono JSON in / JSON out, paginazione tramite ?page= & ?per_page=, filtraggio tramite ?filter[field]= e selezione dei campi tramite ?fields=. Ogni richiesta può portare un header Idempotency-Key.

Autenticazione

Tre tipi di credenziali, due modalità di privacy.

Bearer token LIVE

Email + password · JWT · scadenza 24 ore

JWT a breve durata emesso da POST /v1/auth/login. Contiene le claim di ambito e un ID di revoca della sessione. Rinnovabile per 30 giorni tramite /v1/auth/token/refresh.

Authorization: Bearer eyJhbGciOi••••

Chiave API con ambito limitato LIVE

Lunga durata · con scope · revocabile

Ambiti: read-only, billing-read, billing-write, servers-read, servers-write, full. Lista di IP consentiti opzionale (CIDR), scadenza opzionale. Consigliata per CI e script infrastrutturali.

Authorization: Bearer nb_live_3f9c2a••••

TLS mutuo Planned v1.1

Certificato client · enterprise / compliance

Agganciare un certificato client mTLS a un'API key. Le richieste che presentano il certificato client sbagliato vengono rifiutate al livello TLS prima che venga eseguita qualsiasi logica applicativa. Disponibile su richiesta tramite il pannello.

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

Risposte firmate con PGP Planned v1.1

Firma separata opt-in · verificabile offline

Imposti X-NB-Sign: 1 su qualsiasi richiesta. Il corpo della risposta è avvolto in una firma PGP cleartext separata utilizzando la chiave NordBastion (fingerprint su /pgp/). Utilizzato dalle pipeline di compliance che non si fidano della sola catena TLS.

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

NordBastion non raccoglie l'identità alla registrazione, e l'API non cambia quel livello minimo. Non esiste un webhook di verifica SMS, nessun flusso di conferma email, nessun endpoint di caricamento di documenti d'identità. L'API espone denaro, macchine e metadati — questa è l'intera superficie.

Limiti di frequenza

Per chiave, pubblicato al minuto

Endpoint in lettura: 1000 / min
Endpoint in scrittura: 100 / min
Auth-sensitive: 10 / min
429 retry: Retry-After

Ogni risposta porta X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Livelli più alti sono disponibili su richiesta dal pannello.

Versioning

Periodo minimo di dodici mesi prima della deprecazione

Gli endpoint sono versionati via URL sotto /v1/. Le modifiche incompatibili vengono distribuite solo in una nuova versione major. La major precedente rimane supportata per almeno dodici mesi. Gli endpoint deprecati portano gli header di risposta Sunset e Deprecation.

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

Formato di errore

Envelope stabile, codice leggibile da macchina

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

Webhook

Eventi firmati, ritentati con backoff.

Ogni payload di evento è firmato con HMAC usando il segreto webhook. Tre tentativi di retry con backoff esponenziale nell'arco di un'ora, poi scartato. Test di consegna disponibili da 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.

Endpoint di trasparenza

Accesso programmatico al canary, al log degli incidenti, al record di peering.

La maggior parte delle API cloud espone prodotti e fatturazione. NordBastion espone anche la propria superficie di trasparenza — programmaticamente. Lo stesso warrant canary pubblicato su /warrant-canary/ è disponibile come payload JSON firmato su /v1/transparency/canary. La stessa cronologia degli incidenti che alimenta /status/ è su /v1/transparency/incidents. Lo stesso record di peering che vive su /peering/ è su /v1/transparency/peering. Gli stessi annunci di prefisso AS213232 sono interrogabili in tempo reale.

Si iscriva al webhook canary.updated e riceverà una notifica push il primo giorno di ogni mese — se smette di attivarsi, il canary è compromesso e lo sa senza fare polling. Costruisca l'alert da solo, nella sua infrastruttura, con la firma crittografica che può verificare offline rispetto alla chiave PGP pubblicata.

Questa è la parte dell'API che nessun cloud commerciale ha, perché nessun cloud commerciale ha la dottrina per supportarla.

Esempio · 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"
}

Legga la pagina canary Legga il rapporto di trasparenza La chiave PGP

FAQ · API

Domande degli sviluppatori, con risposta.

Le domande che uno sviluppatore si pone prima di affidare l'infrastruttura all'API di un host.

Esiste davvero un'API ed è KYC-free?

Sì — ogni azione che può eseguire nel pannello di controllo ha un equivalente API oggi o nella roadmap pubblicata, e l'API stessa è protetta dallo stesso account del pannello autenticato: un'e-mail e una password. Non è richiesta alcuna verifica dell'identità per ottenere o utilizzare le credenziali API.

Quali linguaggi di programmazione hanno SDK ufficiali?

Quattro SDK ufficiali e una CLI. Python (pip install nordbastion), TypeScript / Node (npm install @nordbastion/api), Go (go install go.nordbastion.com/cli/nb@latest), Rust (cargo add nordbastion) e una CLI cross-platform a singolo binario (nb) installabile via curl. Tutti gli SDK sono con licenza MIT e disponibili come sorgente.

Posso ricaricare il mio saldo da codice, in criptovaluta?

Sì. POST /v1/billing/topups crea un'intenzione di ricarica e restituisce un indirizzo di destinazione per moneta, codice QR e timestamp di scadenza. Quando la rete conferma il pagamento, il saldo prepagato viene accreditato automaticamente e si attiva un webhook topup.confirmed. Sono supportate dodici criptovalute, elencate su /v1/billing/coins.

Gli endpoint API sono raggiungibili tramite Tor?

L'endpoint clearnet api.nordbastion.com è oggi Tor-friendly senza limiti di frequenza speciali o blocchi anti-Tor. Un mirror onion v3 della superficie API è nella roadmap del pannello e condividerà lo stesso materiale certificato TLS tramite gli header di risposta Onion-Location quando sarà disponibile.

Cosa significa «risposte firmate con PGP»?

Può attivare per la sua chiave API i corpi di risposta firmati con PGP. Ogni risposta JSON è avvolta in una firma PGP cleartext separata utilizzando la chiave NordBastion (fingerprint su /pgp/). Il wrapping è verificabile offline ed è utile per la conformità e l'attestazione della fonte in ambienti che non si fidano della sola catena TLS.

Come vengono applicati i rate limit?

Per API key. La baseline pubblicata è 1000 richieste di lettura al minuto e 100 richieste di scrittura al minuto, più 10 richieste al minuto sugli endpoint auth-sensitive (login, reset password, creazione chiave). Ogni risposta porta gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; le risposte 429 includono un header Retry-After. Gli account sviluppatore verificati possono richiedere livelli più alti dal pannello.

Come funziona il versioning?

Gli endpoint sono versionati via URL sotto /v1/. Le modifiche incompatibili vengono distribuite solo in una nuova versione major (/v2/, /v3/) e la major precedente rimane supportata per almeno dodici mesi dopo il rilascio della successiva. Gli endpoint deprecati portano un header Sunset con la data di interruzione e un header Deprecation: true in ogni risposta.

Perché l'audit log è opt-in?

Perché la dottrina NordBastion dice che registriamo solo ciò che dobbiamo. Le metriche delle richieste operative vivono per la finestra temporale scorrevole di cui ha bisogno il rate-limiter e poi scadono; un audit log per cliente delle azioni API è più dati di quanti ne abbiamo bisogno per gestire la piattaforma, quindi è disattivato di default. I clienti che lo desiderano possono abilitare /v1/account/audit-log; una volta abilitato copre pannello + API in modo equivalente e può essere esportato.

Pronto per automatizzarlo

Ottenere un'API key dal pannello.

Stesso requisito minimo di e-mail e password del pannello. Nessuna verifica d'identità. Paghi in crypto. Avvii un server a Stockholm, Helsinki, Oslo o Reykjavík in circa novanta secondi.

Ottenere API key Veda il catalogo VPS Leggi la dottrina

URL base · https://nordbastion.com/v1/ · Stato · stato operativo in tempo reale · Looking glass · esegua ping/MTR in tempo reale