Call the Ornn API with an API key

Call Ornn directly over HTTPS with JSON requests and an API key. You do not need to install the Ornn CLI or run ornn login. Create a key once in the console, then use it from your application, scripts, or CI. The API reference documents every operation a key can call, with schemas and examples. Download the OpenAPI specification for Postman, Swagger tools, or a client generator.

Setting	Value
Base URL	`https://api.ornn.com`
Authentication	`Authorization: Bearer <your-api-key>`
Request body	JSON, with `Content-Type: application/json`
Organization	Bound to the key; no organization header required
Contract	`https://docs.ornn.com/openapi.yaml`

For a complete cluster integration, start with Provision and manage Kubernetes through REST.

What a key can and cannot do

An API key acts as you in one organization: the organization that was active in the console when you created it. It has the access you have there and nothing more. It never carries Ornn staff access. A key does not bypass organization approval, reservation ownership, payment, or node eligibility. Compute, cluster, storage, and SSH-key operations require an approved organization and return 403 with not_approved otherwise.

With an API key you can	Sign in to the console instead to
Check which account and organization the key resolves to	Create, list, or revoke API keys
Read reservations and their GPU nodes	Edit your profile, preferences, or organization details
Launch machines and clusters on capacity you hold, read their access details, and tear them down	View members, invite teammates, change roles, or remove members
Add, assign, and revoke organization SSH keys	Change notification preferences
Call the other operations in the API reference

Account, team, and key-management routes reject API keys with 403 and detail.code api_key_requires_session. API keys also cannot sign in the CLI or connect an MCP client. Use ornn login for the CLI and the MCP setup for agents. Keys don’t expire. A key stops working as soon as anyone in the organization revokes it, or when its creator leaves the organization.

Create a key

Open the Developer tab

Open Account Settings and select Developer (/account?tab=developer). The tab is available once your organization is approved. Check that the organization you want the key to use is active. Suppliers can use the API tab in the supplier portal instead.

Create the key

Click Create key, enter a name of up to 100 characters such as CI deploys, and confirm.

Copy the key

Copy the key, which starts with ornn_sk_, and store it in your secrets manager. Ornn shows it only once and keeps only a hash, so a lost key cannot be recovered. Create a new one instead.

Treat an API key like a password. Anyone who has it can act as you in that organization until the key is revoked.

Create keys for long-running automation from an account that will stay in the organization. If the key’s creator leaves, the key is deleted and the automation stops.

Use a key

Send the key in the Authorization header as a bearer token. The key already belongs to its organization, so you don’t need to name the organization in the request. Start by checking which account and organization the key resolves to.

export ORNN_API_KEY="ornn_sk_example..."

curl --fail-with-body https://api.ornn.com/v1/auth/session \
  -H "Authorization: Bearer $ORNN_API_KEY"

import os

import requests

response = requests.get(
    "https://api.ornn.com/v1/auth/session",
    headers={"Authorization": f"Bearer {os.environ['ORNN_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
session = response.json()
organization_id = session["organizations"][0]["id"]
print(session["email"], organization_id)

A working key returns 200 with your account and exactly one entry in organizations: the organization you created the key in. Save that id; routes such as List organization SSH keys take it in the path. Check approved before calling operations that need an approved organization. A 401 means the key was revoked, mistyped, or its creator is no longer a member of that organization. See Check API authentication for the full response. Suppliers: see Use the supplier API for node, telemetry, enrollment, and listing routes.

Import the OpenAPI contract

The contract at https://docs.ornn.com/openapi.yaml is OpenAPI 3.1. Its server is https://api.ornn.com and its security scheme is a bearer token.

Postman
Swagger UI
Client generators

Choose Import and paste https://docs.ornn.com/openapi.yaml. Postman creates a collection with one request per operation.
Store your key in a secret environment or vault variable, for example ornnApiKey.
On the collection’s Authorization tab, choose Bearer Token and set the token to {{ornnApiKey}}. Requests set to inherit authorization use it.
Send Check API authentication first to confirm the key and organization.

Open the contract in Swagger UI or Swagger Editor with the same URL, then use Authorize to enter the key as a bearer token. Use these tools to browse schemas and generate client code.Browsers block requests to api.ornn.com from pages on other sites, so Try it out in a hosted Swagger page fails. Send requests from Postman’s desktop app, curl, or your own server code.

Generate a client with a tool that supports OpenAPI 3.1, such as OpenAPI Generator. Configure the generated client with base URL https://api.ornn.com and bearer authentication, and read the key from your secret store at runtime.Re-download the contract when you upgrade; info.version identifies the revision you generated against.

Keep keys out of browser code, mobile apps, and public repositories. Call the API from a server, job runner, or CI system that reads the key from a secret store.

Rotate a key

Keys don’t expire, so rotate them on your own schedule, when someone with access to the key leaves, or immediately if a key may be exposed.

Create the replacement

Create a new key in Account Settings → Developer with a name that identifies it, such as CI deploys 2026-10.

Deploy and verify it

Store the new key in your secrets manager and roll it out. Confirm it returns 200 from GET /v1/auth/session with the expected organization.

Revoke the old key

Revoke the old key after every system has switched. Requests that still use it start failing with 401.

Both keys work during the rollout, so you can switch without downtime.

Revoke a key

Find the key

Open Account Settings → Developer. The list shows every key in your organization, its name, whether you or a teammate created it, and when.

Revoke it

Click Revoke on the key and confirm. Anything using the key stops working immediately. This can’t be undone.

Any member of the organization can revoke any of its keys. When a member leaves the organization, their keys are removed automatically. The Ornn CLI and the REST API use different credentials. The CLI does not read an API key from a flag or environment variable; it always uses the session ornn login stores.

	`ornn login` session	API key
Used by	The `ornn` CLI	Your code, scripts, and CI over HTTPS
How you get it	Approve the browser device sign-in	Create key in Account Settings → Developer
Organizations	Every organization you belong to; switch with `ornn context`	Exactly one
Ends when	You run `ornn logout`, or after 14 days without use	Anyone in the organization revokes it, or you leave the organization
Where it is stored	`auth.json` in `~/.config/ornn`, readable only by you	Your secrets manager

Use the CLI for interactive work and the API for unattended integrations. See CLI and REST equivalents to translate a CLI command into an API request.

Reservation REST reference

These routes read reservations visible to your key’s organization: reservations it holds and sales against listings it supplies. Visibility of a sale does not grant the supplier the buyer’s cluster-launch rights. Cluster creation uses existing eligible reserved capacity; it does not buy GPUs or bypass approval, payment, or reservation dates.

List reservations: GET /commerce/reservations returns reservations and nextCursor.
Get a reservation: GET /commerce/reservations/{reservationId} returns one reservation.
List reserved GPU nodes: GET /v1/orchestrator/nodes?reservation_id={reservation_id} returns the nodes of a reservation you hold.

curl --fail-with-body 'https://api.ornn.com/commerce/reservations?limit=100' \
  -H "Authorization: Bearer $ORNN_API_KEY"

Each reservation includes reservationId, status, startsAt, endsAt, reservedNodeCount, and reservedGpuCount. Use reservationId, not a listing ID, in the cluster launch request. When nextCursor is nonempty, send it unchanged as the URL-encoded cursor query parameter on the next request. Continue until it is absent, null, or empty. Reservation fields use camelCase; cluster request fields use snake_case. See Create a cluster for the request and response schema, or follow the complete Kubernetes REST walkthrough.

Errors and safe retries

401: check that the bearer key is correct, not revoked, and its creator still belongs to the organization. Repeated requests with a rejected key from one address are throttled with 429.
403: the key does not grant the required access. Most operations require an approved organization; creating a key does not grant approval. api_key_requires_session means the operation needs a signed-in console session.
404: verify resource ownership and IDs. Cluster credentials can also return 404 while they are not ready.
400 or 422: check request fields, UUIDs, and supported values.
409: resolve the reported state or capacity conflict before retrying.
429 or 5xx: back off before retrying reads; honor Retry-After when provided.

Customer errors normally include detail.code and detail.message. Some routes return a string detail, a top-level code or error, or no JSON body. Always check the HTTP status before decoding success fields; preserve the sanitized response when contacting support. A successful launch or worker-add response means the operation was accepted, not that GPUs are ready. Poll status and verify readiness. After a timeout on a write, read current state before retrying: do not assume the write failed. Only some routes accept an Idempotency-Key; see Retries and idempotency. Never log API keys or cluster credentials.

Get Started

Buy and sell

Supplier

Accessing Compute

Storage

Nodes

Account

Call the Ornn API with an API key

What a key can and cannot do

Create a key

Use a key

Import the OpenAPI contract

Rotate a key

Revoke a key

Reservation REST reference

Errors and safe retries

​What a key can and cannot do

​Create a key

​Use a key

​Import the OpenAPI contract

​Rotate a key

​Revoke a key

​CLI sign-in and API keys

​Reservation REST reference

​Errors and safe retries

What a key can and cannot do

Create a key

Use a key

Import the OpenAPI contract

Rotate a key

Revoke a key

CLI sign-in and API keys

Reservation REST reference

Errors and safe retries