API quickstart

API keys let your own scripts and CI act for your organization. Each key carries only the scopes you give it.

Create a key

1. Turn on two-factor authentication in Settings. Creating a key requires it.
2. In the console, open Keys and choose Create key.
3. Name the key after what uses it, for example ci-runner.
4. Pick its scopes and its lifetime: 30, 90, 180 or 365 days.
5. Optionally, set its spending limits (see below).
6. Copy the key. It is shown once.

Owners and admins of the organization manage keys. Each new key is announced by email to the person who created it.

Authenticate

Send the key as a Bearer token:

export NODELODGE_API_KEY="nl_live_..."
curl https://nodelodge.com/v1/whoami \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

The answer names the organization and the scopes the key carries:

{
  "orgId": "6f1c...",
  "via": "api_key",
  "apiKeyId": "2b9e...",
  "scopes": ["workloads:read"]
}

Use whoami in a pipeline to fail fast on a revoked, expired or mistyped key.

Reference

Every endpoint, with its parameters and a curl example, is in the API reference. The same description is published as an OpenAPI 3.1 document at https://nodelodge.com/v1/openapi.json: import it in your HTTP client, or generate a typed client from it.

curl https://nodelodge.com/v1/openapi.json -o nodelodge-openapi.json

Scopes

Give each key the fewest scopes its job needs. A key that only reports status needs workloads:read.

What a key can call

A key raises the budget and reads the connection details of the sessions it launched only. Any key of the organization with workloads:write can stop a session.

Launch a session

curl -X POST https://nodelodge.com/v1/sessions \
  -H "Authorization: Bearer $NODELODGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"partnerOfferId":"3f0c8f5e-8c3a-4f39-9a8e-2d9b4c1e7a10","environmentId":"jupyterlab","pricing":"on_demand","budgetCents":2000,"allowedCidr":"203.0.113.7","sshPublicKey":"ssh-ed25519 AAAA... you@laptop"}'

• budgetCents is the most the session may cost. It is reserved on your credit at launch. Billing follows the real time the machine runs, from the moment it is ready, and Budget Guard stops the session before the budget is spent.
• allowedCidr is the public IPv4 address, or a range up to /24, allowed to connect over SSH.
• sshPublicKey opens this session only: it is not saved on your account. To use a key saved in the console, send its id in sshKeyIds instead. Saving or removing a key on your account is done in the console.
• environmentId: data-center machines run jupyterlab. GET /v1/environments?offerId=... lists what a Community machine can run.
• Add maxDurationHours to stop the session after that many hours, even with budget left.
• The Idempotency-Key header makes a retried request start one session.

Read the session with GET /v1/sessions/{id}: once its status is ready, directSsh gives the host, user and port. Raise its budget with POST /v1/sessions/{id}/budget, and stop it with POST /v1/sessions/{id}/stop: billing ends and the rest of the budget is released.

When POST /v1/sessions answers 409 RESERVATION_REQUIRED, book the machine with POST /v1/reservations (partnerOfferId and durationHours, or mode: "on_demand"), then start it with POST /v1/reservations/{id}/start. A fixed duration holds its full price, and maxCostCents refuses the booking when that amount would exceed it. On demand, the amount held covers the next 60 minutes and is renewed while the machine runs. In both cases you are billed per started minute of real use, with no one-hour minimum.

To drive sessions from an AI agent, use the MCP server.

Spending limits

Each key can carry limits, enforced by Node Lodge when a session is launched, when its budget is raised, and each time an on-demand reservation is extended:

A launch or a raise that would go past a limit answers 409 API_KEY_LIMIT and reserves nothing. Requests made at the same time with one key are checked one after the other, so they cannot pass a limit together. A key without limits is still bounded by your available credit and your account limits. Owners and admins change the limits of a live key with Edit limits in Keys, after a fresh two-factor code. Sessions launched from the console are not limited by any key.

Account settings, keys, saved SSH keys, cards and two-factor stay in the console: a request with an API key to those answers 403 API_KEY_NOT_ALLOWED. Every action made with a key is listed in Activity, with the key that made it.

Errors

Error bodies have the same shape everywhere:

{ "error": { "code": "API_KEY_NOT_ALLOWED", "message": "...", "reference": "7F3K-92QD" } }

reference identifies the request. Log it with the error, and include it when you write to support.

Keep keys safe

• Store keys in your secret manager or CI secrets, never in code.
• One key per tool, so you can revoke one without touching the others.
• Revoke a key in Keys the moment it leaks. Requests using it stop at once.
• Every key creation and revocation is listed in Activity.