API Reference
Server Registration

Server Registration

Mint single-use Quick Connect tokens to add servers to your organization without leaving your own control panel. Built for platforms and internal tools built on top of oec.sh.

Base URL: https://api.oec.sh/api/public/v1

⚠️

Disabled by default. Server registration is a separate capability from the rest of the Public API — creating billable infrastructure is a different power from deploying code. Even a full-access API key cannot use these endpoints until an oec.sh administrator enables it for that specific key. Ask support if you need it turned on.

Requires an organization-scoped, full-access API key with server registration enabled. See API Keys for tiers and scopes.

Create a Registration Token

POST /servers/registration-tokens

Mints a single-use token and the shell command to install the oec.sh agent on a server. The token is returned once, in plaintext — only its hash is stored.

Request Body

FieldTypeDescription
server_namestring | nullOptional label for the server.
ssh_usernamestringUser the platform will SSH in as once the agent connects. Default root.
expires_instringOne of 1h, 6h, 24h, 48h, 7d. Default 24h.
auto_deployobject | nullOptional auto-deploy configuration to apply once the server registers.

Response — 201 Created

{
  "token_id": "b9e2a2b0-6f9a-4e2b-8b1a-2c9e6f9a4e2b",
  "token": "srt_live_9f8e7d6c5b4a3f2e1d0c...",
  "install_command": "curl -sfL https://api.oec.sh/api/v1/install.sh | sudo OECSH_TOKEN=srt_live_9f8e7d6c5b4a3f2e1d0c... bash",
  "expires_at": "2026-09-04T12:00:00Z",
  "status": "pending"
}

Run install_command on the target server (as root or with sudo). See Servers for what happens after the agent connects.

Example

curl -X POST "https://api.oec.sh/api/public/v1/servers/registration-tokens" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_name": "client-prod-1", "expires_in": "24h"}'

Errors

StatuserrorMeaning
403org_scope_requiredThe key is project-scoped, not organization-scoped.
403write_access_requiredThe key is read-only.
403server_registration_not_enabledThe key hasn't been enabled for this capability — see the callout above.
409key_has_no_ownerThe user who created this API key no longer exists. Rotate the key.
409server_quota_exceededYour organization's server quota is exhausted, including reserved (unconsumed) tokens.

List Registration Tokens

GET /servers/registration-tokens

Returns every registration token for your organization — pending, consumed, expired, and revoked.

Response — 200 OK

[
  {
    "token_id": "b9e2a2b0-6f9a-4e2b-8b1a-2c9e6f9a4e2b",
    "token_prefix": "srt_live_9f8e",
    "server_name": "client-prod-1",
    "status": "pending",
    "expires_at": "2026-09-04T12:00:00Z",
    "created_at": "2026-09-03T12:00:00Z",
    "created_by_name": "Jane Doe"
  }
]

Only token_prefix is returned, never the full token — it was shown once at creation and cannot be retrieved again.

Revoke a Registration Token

DELETE /servers/registration-tokens/{token_id}

Revokes an unconsumed token and frees its reserved server-quota slot. Returns 204 No Content on success, 404 if the token doesn't exist or was already consumed.

Example

curl -X DELETE "https://api.oec.sh/api/public/v1/servers/registration-tokens/YOUR_TOKEN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Troubleshooting

403 server_registration_not_enabled

This is a per-key switch, off by default even for full-access keys. Contact oec.sh support with the key name to have it enabled.

Install command fails on the server

Confirm the token hasn't expired (expires_at) and hasn't already been consumed by a previous run of the install command — tokens are single-use.

Quota exceeded but I don't have that many servers

Unconsumed pending tokens reserve a quota slot. Revoke tokens you're not going to use to free them up.

EnvironmentsBackups