Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceComputeSSH Keys

Add an SSH public key (computes fingerprint)

Registers an OpenSSH public key for the org, stores it in canonical form with its computed fingerprint, and returns it with its new id and creation time. An invalid key answers 400 INVALID_KEY, and a key that is already registered answers 409 KEY_EXISTS.

Required permission

Requires the sshkey.write permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl ssh-keys create --name <name> --public-key <public-key>
POST
/v1/orgs/{orgId}/ssh-keys/create

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

orgId*string

Request Body

application/json
  1. body
name*string
publicKey*string

Exactly one OpenSSH public key on a single line: the key type, the base64 key, and an optional comment, as in a .pub file. The comment must be printable text without control characters, ,, $, % or a grapheme-prepend letter (such as U+0D4E), and authorized_keys options such as from= are refused. The key is stored and returned in canonical form, with single spaces between the fields and the comment in Unicode NFC.

Response Body

Added

application/json
  1. response
id*string
name*string
publicKey*string
fingerprint*string
createdAt*string
attachedVmCount?integer

Number of live (non-terminated) VMs this key is attached to. Zero means the key is not scoped to any VM. The dashboard shows an "in use" indicator and warns before deleting a key that is in use.

blockingVms?array<string>

Names of VMs for which this is the only key that still resolves to a live org key. Deleting the key is refused (409) while this is non-empty; attach another key to those VMs first.

Example Request
curl -X POST 'https://api.openrelay.inc/v1/orgs/string/ssh-keys/create' \  -H 'Content-Type: application/json' \  -d '{  "name": "work-laptop",  "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEwYmWtgYXGvpnO7ydkeXv/nNhu3SoxSi8C9u8hMatr8 user@laptop"}'
Example Response
{  "id": "string",  "name": "string",  "publicKey": "string",  "fingerprint": "string",  "createdAt": "string",  "attachedVmCount": 0,  "blockingVms": [    "string"  ]}

List an org's SSH public keys GET

Returns the org's SSH public keys with their fingerprints, how many live VMs each is attached to, and the VMs for which each is the only remaining key.

Delete an SSH public key DELETE

Deletes an SSH public key from the org and scrubs it from every VM it was attached to, unless it is the only key that still grants access to one of them. That case is refused with 409 (code KEY_IN_USE), since deleting it would strand that VM; attach another key to those VMs first. listOrgSshKeys reports this as blockingVms.