Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview

Register an SSH public key for the org's sandboxes

The SSH gateway lets the holder of any registered key into every running sandbox of the org, as the sandbox user. The key belongs to the user of the API key that registers it and works only while that user is an active user of the org: removing them from the org deletes it, and so does revoking the API key that registered it. A key can be registered once per org (409 otherwise).

POST/v1/ssh-keys
Authorization
AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Request body
requiredapplication/json
public_keystringrequired

One public key in authorized_keys format (ssh-ed25519 AAAA... comment), for example the contents of ~/.ssh/id_ed25519.pub. Options before the key type, certificates and DSA keys are refused; RSA keys need at least 2048 bits.

min length 1 · max length 16384
namestring

A label. Default the key's comment, else its fingerprint.

max length 100
Responses
201

The registered key.

idstringrequired
namestringrequired
fingerprintstringrequired

SHA-256 fingerprint, as ssh-keygen -l prints it.

public_keystringrequired

The key in authorized_keys format, without its comment.

user_emailstringrequired

The email address of the user the key belongs to.

created_atstring<date-time>required
429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

Request
curl -X POST 'https://api.pols.so/v1/ssh-keys' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "public_key": "string",
  "name": "string"
}'
Response
{
  "id": "ssh_4n8c2k7w1p0d",
  "name": "string",
  "fingerprint": "SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl",
  "user_email": "ada@example.com",
  "created_at": "2019-08-24T14:15:22Z"
}