Skip to content

Add an SSH key

Register an SSH public key or create a token for a Computer's private website. Limit a public key to one Computer or tag if needed. To get a website-only token, name a Computer with computer and omit the public key. Heaven returns that token once and revokes it when you remove its key.

Parameters

#
public_keystring
SSH public key text, such as the contents of ~/.ssh/id_ed25519.pub. To create a private website token, omit the public key and give computer.
labelstring
Label to identify the key in ssh-key view. A website token's key defaults to site token.
tagstring
Limit an SSH key to Computers with this tag. Use one tag of lowercase letters, digits and hyphens. Use this field or computer.
computerstring
Name or ID of the only Computer this key can reach. Without a public key, creates a token for that Computer's private website. Use this field or tag.

Returns

#
dataobjectAlways present
A registered SSH key or a private-site token.
Show 2 attributesHide attributes
alternative-1object
A registered SSH public key and its access restrictions.
Show 8 attributesHide attributes
computerobject
Single Computer this key can reach, when it is limited to one. May be omitted.
Show 2 attributesHide attributes
idstringAlways present
Selected Computer's ID.
namestringAlways present
Current name; empty during deletion or after you lose access.
created_atstring (date-time)
Time the key was added. May be omitted.
fingerprintstringAlways present
Public key fingerprint.
idstringAlways present
Registered key's ID.
labelstringAlways present
User-assigned label.
last_used_atstring (date-time) | nullAlways present
Last recorded SSH sign-in; null if none is recorded. Updates can take five minutes.
public_keystringAlways present
SSH public key.
tagstring
Tag limiting the key to matching Computers, when set. May be omitted.
alternative-2object
A token for a Computer's private website and the key that signed it.
Show 3 attributesHide attributes
keyobjectAlways present
Registered key that signed the token.
Show 8 attributesHide attributes
computerobject
Single Computer this key can reach, when it is limited to one. May be omitted.
Show 2 attributesHide attributes
idstringAlways present
Selected Computer's ID.
namestringAlways present
Current name; empty during deletion or after you lose access.
created_atstring (date-time)
Time the key was added. May be omitted.
fingerprintstringAlways present
Public key fingerprint.
idstringAlways present
Registered key's ID.
labelstringAlways present
User-assigned label.
last_used_atstring (date-time) | nullAlways present
Last recorded SSH sign-in; null if none is recorded. Updates can take five minutes.
public_keystringAlways present
SSH public key.
tagstring
Tag limiting the key to matching Computers, when set. May be omitted.
sitestringAlways present
Private website this token reaches.
tokenstringAlways present
Private-site token, returned only on creation.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • Requires the dashboard or management SSH with a registered key.
  • A key limited to a command list cannot run this command.