Create an SSH key
Adds a public key at one level: a company or a website (for all or for selected environments), one environment, or yourself. A personal key logs in with your own username; every other key logs in as web. Adding a company key needs the Create Company SSH Keys permission.
Body
For company and website keys only. Left out, the key applies to all environments. The environments a company or website key applies to: the word all, {mode: all}, or a selection. A selection with environment_ids and no mode means selected.
Fields
A name to recognise the key by. Up to 100 characters.
The owner of a key in a request.
Fields
The id of the environment, website or company. For user, your own user id, which GET /user/ssh answers in user_id. At least 1.
The level the key is held at. user is yourself.
environmentwebsitecompanyuserOne public key. An OpenSSH line (ssh-ed25519 AAAA… comment) is taken as it is; a PEM, RFC 4716 or PKCS#1 public key is converted to it. Never send a private key. At most 16,384 bytes, counted without the white space around it: a longer value is refused ssh_key_invalid, and one over 20,000 characters invalid_arguments.
Returns
201 The key was added. Follow change_id with GET /ssh/changes/{change} to see it applied.
Fields of the 201 answer
The change to follow with GET /ssh/changes/{change}. Null when nothing needs applying.
The format the key was sent in, when it was converted to the one-line OpenSSH format: pem (BEGIN PUBLIC KEY), pem_rsa (BEGIN RSA PUBLIC KEY), ssh2 (BEGIN SSH2 PUBLIC KEY, RFC 4716), bare (the key data of one of those without its first and last lines) or wrapped (an OpenSSH line broken across lines). Null for a key sent as one OpenSSH line.
pempem_rsassh2barewrappednullA key held at one owner: a company, a website, an environment or a person.
Fields
Format: date-time.
Who added a key or made a change.
Fields
True when the person has left the company.
Null when the person has been removed, or when Corefinity support made the change for nobody by name.
True when Corefinity support added the key or made the change. name is then the person it was done for, or null.
Other places the same key is held that you can see.
Fields of each item
agencycompanywebsiteenvironmentuserlegacysystemWhere a key is held: a company, a website, an environment or a person.
Fields
The id of the company, website, environment or user.
companywebsiteenvironmentuserNull for environment and personal keys.
The key size, for RSA keys.
Where the key works so far, counted over the environments it reaches.
Fields
Environments the key works on.
Environments whose keys the Control Panel does not manage yet.
For a key being removed, environments it no longer works on.
appliedapplyingremovingfailedwaitingEnvironments the key reaches, without those in not_on_new_system.
Environments where the key, or its removal, waits for the environment to switch over or for a platform update.
How many of waiting wait for a platform update.
Whether you may rename the key or change where it applies.
The SHA-256 fingerprint, as ssh-keygen -lf prints it. Removing the key, or narrowing where it applies, asks you to send it back.
The key id the /ssh/keys/{key} endpoints take.
Format: date-time.
The level the key is held at, as you see it. agency is a key of your agency.
agencycompanywebsiteenvironmentuserlegacysystemSet for a Legacy key, else null.
quarantined is a key Corefinity has stopped from working; quarantine_reason says why.
activeremovingquarantinedThe username the key logs in with: web, or the person's own username for a personal key (null until one is issued).
Where a key is held: a company, a website, an environment or a person.
Fields
The id of the company, website, environment or user.
companywebsiteenvironmentuserHow far a key reaches.
Fields
Client companies an agency's key reaches.
Whether you may remove the key.
True when the key carries restrictions from before it was imported.
The restrictions as they are written in front of the key. Read-only.
The key type, such as ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521 or ssh-rsa. A key imported from a server may carry an older type (ssh-dss) or a security-key type (sk-), which new keys may not.
ssh-ed25519ecdsa-sha2-nistp256ecdsa-sha2-nistp384ecdsa-sha2-nistp521ssh-rsassh-dss[email protected][email protected]True for a key that would be refused if it were added today.
Fields of each item
also_grantedstays_restrictedconvertedweak_importIf it is refused
| Status | Reason | What to do |
|---|---|---|
401 | none | Send a valid token as Authorization: Bearer <token>. |
403 | company_unavailable | Your company is unavailable. |
403 | forbidden | The person is not allowed to do this. |
403 | scope_required | Use a token with the scope named in scope. |
403 | two_factor_required | Turn on two-factor on your account, then send again. |
404 | feature_off | This feature is not on for your organisation yet. |
404 | not_found | Not found. |
409 | ssh_key_duplicate | The key is already added here. Use the existing one. |
409 | ssh_managed_on_another_environment | This environment's SSH is managed on another environment. Make the change on the environment the answer names. |
422 | invalid_arguments | The arguments do not match the tool's input schema, or the Control Panel refused a field. Fix the fields named in the answer and call again. |
422 | ssh_cap_exceeded | There are too many keys here. Remove one you no longer need. |
422 | ssh_key_invalid | That is not an SSH public key Corefinity can use. Paste one OpenSSH public key. |
422 | ssh_key_weak | The key is too weak. Use an ed25519 key, or RSA of at least 3072 bits. |
429 | ssh_throttled | Too many SSH key changes — try again in a minute. |
429 | rate_limited | Wait for the seconds in Retry-After. |
Reasons are listed by name in Errors and refusals.
The same task elsewhere
curl -X POST https://manage.corefinity.com/api/ssh/keys \
-H "Authorization: Bearer $COREFINITY_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"applies_to": {
"environment_ids": [
1311
],
"mode": "selected"
},
"name": "Build server",
"owner": {
"id": 1204,
"type": "company"
},
"public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey2"
}'use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('COREFINITY_TOKEN'))
->acceptJson()
->post('https://manage.corefinity.com/api/ssh/keys', [
'applies_to' => [
'environment_ids' => [
1311,
],
'mode' => 'selected',
],
'name' => 'Build server',
'owner' => [
'id' => 1204,
'type' => 'company',
],
'public_key' => 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey2',
]);
$data = $response->json();const res = await fetch('https://manage.corefinity.com/api/ssh/keys', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
applies_to: {
environment_ids: [
1311,
],
mode: 'selected',
},
name: 'Build server',
owner: {
id: 1204,
type: 'company',
},
public_key: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey2',
}),
});
// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);import os
import requests
res = requests.post(
"https://manage.corefinity.com/api/ssh/keys",
headers={
"Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
"Accept": "application/json",
},
json={
"applies_to": {
"environment_ids": [
1311,
],
"mode": "selected",
},
"name": "Build server",
"owner": {
"id": 1204,
"type": "company",
},
"public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey2",
},
)
data = res.json() if res.content else None{
"change_id": 48211,
"converted_from": null,
"key": {
"added_at": "2026-11-05T09:16:40+00:00",
"added_by": {
"former": false,
"name": "Eleanor Finch",
"support": false
},
"also_granted": [],
"applies_to": {
"environment_ids": [
1311
],
"mode": "selected"
},
"bits": null,
"delivery": {
"applied": 0,
"not_on_new_system": 0,
"removed": 0,
"state": "applying",
"total": 1,
"waiting": 0,
"waiting_platform_update": 0
},
"editable": true,
"fingerprint": "SHA256:CLqzToSA4nOd3+meykf1UbpDyB5Jwm32ErgxuitkRIU",
"id": 7307,
"last_used_at": null,
"layer": "company",
"legacy": null,
"lifecycle": "active",
"login": "web",
"name": "Build server",
"owner": {
"id": 1204,
"name": "Harbour & Finch",
"type": "company"
},
"quarantine_reason": null,
"reach": {
"clients": 0,
"environments": 1,
"websites": 1
},
"removable": true,
"restricted": false,
"restrictions": [],
"type": "ssh-ed25519",
"weak": false
},
"notices": []
}{
"message": "Unauthenticated."
}{
"code": "company_unavailable",
"message": "Your company is unavailable.",
"reason": "company_unavailable"
}{
"code": "feature_off",
"message": "Not found.",
"reason": "feature_off"
}{
"code": "ssh_key_duplicate",
"field": "public_key",
"message": "That key is already added here.",
"reason": "ssh_key_duplicate"
}{
"code": "invalid_arguments",
"errors": {
"comment": [
"comment is not part of this request."
]
},
"field": "comment",
"message": "comment is not part of this request.",
"reason": "invalid_arguments"
}{
"code": "ssh_throttled",
"field": null,
"message": "Too many SSH key changes — try again in a minute.",
"reason": "ssh_throttled"
}Try it is off for this endpointIt has not been cleared for the console. Copy the request and run it yourself when you are sure.