NordBastion 北极熊吉祥物坐在战术任务控制工作站，悬浮的全息终端显示器呈现青色代码，带青色发光键帽的机械键盘和青色 N 形盾牌靠在身旁，置身于裸露 Nordic 石墙的控制室内，窗外极光映照

API.v1 · REST · 70+ 个端点 · 5 个 SDK

通过代码运行 NordBastion。
无 KYC，加密货币付款，完全可脚本化。

配置服务器、创建快照、以加密货币充值、从任意堡垒运行 ping。每个面板操作都有一个 REST 端点和四个 SDK。与面板相同的身份底线：邮箱和密码，仅此而已。

快速入门所有端点

版本: v1
端点: 70+
SDK: 4 + CLI
堡垒节点: 4 Nordic
速率限制: 1000/min read
KYC: 无

快速入门

从注册账户到通过代码启动服务器，三个步骤。

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 用加密货币充值

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 配置服务器

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

四种语言，一个二进制文件。

每个 SDK 均为 MIT 许可、源代码可用、从 v1.0 起遵循 semver 稳定版本。所有 SDK 共享相同的认证客户端接口——用任意语言列出服务器。

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 优先

REST API 与任何 HTTP 客户端兼容。JSON 请求和响应体，JWT bearer 或限定范围的 API 密钥，已签名的 webhook 载荷。无 SDK 锁定。

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

端点参考

跨越十二个资源组的 70+ 个端点。

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

所有端点遵循 JSON 输入/JSON 输出，分页使用 ?page= 和 ?per_page=，过滤使用 ?filter[field]=，字段选择使用 ?fields=。每个请求均可携带 Idempotency-Key 头。

认证

三种凭证类型，两种隐私模式。

Bearer token LIVE

邮箱 + 密码 · JWT · 24 小时过期

通过 POST /v1/auth/login 签发的短期 JWT。携带权限声明和会话撤销 ID。可通过 /v1/auth/token/refresh 在 30 天内刷新。

Authorization: Bearer eyJhbGciOi••••

限定范围的 API 密钥 LIVE

长期有效 · 有范围限制 · 可撤销

权限范围：只读、账单读取、账单写入、服务器读取、服务器写入、完全权限。可选 IP 白名单（CIDR），可选有效期。推荐用于 CI 和基础设施脚本。

Authorization: Bearer nb_live_3f9c2a••••

双向 TLS Planned v1.1

客户端证书 · 企业 / 合规

将 mTLS 客户端证书绑定到 API 密钥。提交错误客户端证书的请求在任何应用逻辑运行之前就在 TLS 层被拒绝。可通过面板申请。

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

PGP 签名响应 Planned v1.1

可选择的独立签名 · 可离线验证

在任意请求上设置 X-NB-Sign: 1。响应体将使用 NordBastion 密钥（指纹见 /pgp/）封装为分离式 PGP 明文签名。适用于不完全信任 TLS 链的合规管道。

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

NordBastion 在注册时不收集身份信息，API 不改变这一底线。没有 SMS 验证 webhook，没有邮箱确认流程，没有身份证件上传端点。API 暴露的是资金、机器和元数据——这就是全部接触面。

速率限制

按密钥，每分钟已公布

只读端点: 1000 / min
写入端点: 100 / min
对认证敏感: 10 / min
429 重试: Retry-After

每个响应均携带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。更高限额可通过面板申请。

版本管理

十二个月弃用保护期

端点在 /v1/ 下进行 URL 版本控制。破坏性变更仅在新主版本中发布。前一主版本至少支持十二个月。已弃用的端点携带 Sunset 和 Deprecation 响应头。

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

错误格式

稳定封装，机器可读代码

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

Webhook

已签名事件，带退避重试。

每个事件负载均使用你的 webhook 密钥进行 HMAC 签名。在一小时内进行三次指数退避重试，之后丢弃。可通过 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.

透明度端点

对金丝雀声明、事件日志和对等互联记录的编程访问。

大多数云 API 暴露产品和计费信息。NordBastion 也以编程方式暴露自己的透明度界面。发布于 /warrant-canary/ 的相同金丝雀声明可作为签名 JSON 负载在 /v1/transparency/canary 获取。驱动 /status/ 的相同事件历史在 /v1/transparency/incidents。位于 /peering/ 的相同对等互联记录在 /v1/transparency/peering。相同的 AS213232 前缀公告可实时查询。

订阅 canary.updated webhook，每月第一天您将收到推送通知——若推送停止，金丝雀已断，无需轮询即可知晓。在您自己的基础设施中构建告警，使用可离线对照已发布 PGP 密钥验证的加密签名。

这是任何商业云都不具备的 API 部分，因为没有任何商业云有原则立场支撑它。

示例 · 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"
}

查看金丝雀页面查看透明度报告 PGP 密钥

FAQ · API

开发者问题，逐一解答。

开发者在将基础设施对接主机 API 之前必问的问题。

真的有 API 吗？它是无 KYC 的吗？

是——控制面板中您能执行的每个操作，今天或在已发布的路线图中均有对应的 API 等效方式，API 本身由相同的已认证控制面板账户（电子邮件和密码）守护。获取或使用 API 凭证无需身份验证。

哪些编程语言有官方 SDK？

四个官方 SDK 和一个 CLI。Python（pip install nordbastion）、TypeScript / Node（npm install @nordbastion/api）、Go（go install go.nordbastion.com/cli/nb@latest）、Rust（cargo add nordbastion）以及可通过 curl 安装的单二进制跨平台 CLI（nb）。所有 SDK 均为 MIT 许可且源代码可用。

我可以通过代码以加密货币充值余额吗？

是的。POST /v1/billing/topups 创建充值意图并返回每种币种的目标地址、二维码和到期时间戳。网络确认支付后，您的预付余额自动到账，并触发 topup.confirmed webhook。支持十二种加密货币，列表见 /v1/billing/coins。

API 端点可以通过 Tor 访问吗？

明网端点 api.nordbastion.com 目前对 Tor 友好，无特殊速率限制或反 Tor 封锁。API 的 v3 onion 镜像在控制面板路线图中，上线时将通过 Onion-Location 响应头共享相同的 TLS 认证内容。

「PGP 签名响应「是什么意思？

您可以为 API 密钥选择启用 PGP 签名响应体。每个 JSON 响应使用 NordBastion 密钥（指纹见 /pgp/）封装为分离式明文 PGP 签名。该封装可离线验证，适用于不完全信任 TLS 链的合规和来源证明场景。

速率限制是如何执行的？

按 API 密钥计。已发布的基准为每分钟 1000 个读取请求和 100 个写入请求，加上认证敏感端点（登录、密码重置、密钥创建）每分钟 10 个请求。每个响应携带 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头；429 响应包含 Retry-After 头。已验证的开发者账户可通过面板申请更高限额。

版本控制如何运作？

端点在 /v1/ 下进行 URL 版本控制。破坏性变更仅在新主版本（/v2/、/v3/）中发布，前一主版本在下一版本发布后至少支持十二个月。已弃用的端点在每个响应上携带包含截止日期的 Sunset 头和 Deprecation: true 头。

为何审计日志是可选启用的？

因为 NordBastion 的原则是只记录必须记录的内容。运营请求指标在速率限制器所需的滚动窗口内存在，之后过期；每个客户的 API 操作审计日志所包含的数据超出运营平台的需要，因此默认关闭。需要的客户可以启用 /v1/account/audit-log；一旦启用，它同等覆盖面板和 API，并可导出。

准备好脚本化操作

从面板获取 API 密钥。

与控制面板相同的邮箱加密码注册门槛。无需身份验证。以加密货币支付。约九十秒内启动 Stockholm、Helsinki、Oslo 或 Reykjavík 服务器。

获取 API 密钥查看 VPS 目录阅读准则

基础 URL · https://nordbastion.com/v1/ · 状态 · 实时运营状态 · 网络测速镜像 · 实时运行 ping/MTR