Create a key for a user
Adds a public key to one of the site's users. A key added to the built-in web user, while SSH keys are on for your company, is a key for the whole environment: it is answered as POST /ssh/keys answers, followed with GET /ssh/changes/{change}, and counts against the limit on key changes (30 a minute for you, 120 for your company).
Path parameters
The id of a site row. A website's production site and each of its environments has its own id. Digits only. At least 1.
The id of one of the site's users, as GET /corestack/sites/{site}/access answers it. Digits only. At least 1.
Body
One public key, in OpenSSH, PEM or PuTTY format. At most 16,384 bytes once the space around it is trimmed: a longer one is refused as too long to be a public key.
A name to recognise the key by. Up to 64 characters.
Returns
201 The key was added. For a named user the answer is the key and its operation. For the built-in web user, while SSH keys are on, it is the environment key with a change_id.
Fields of the 201 answer
If 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 | scope_required | Use a token with the scope named in scope. |
403 | restricted | Restricted keys are changed by staff. |
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. |
409 | busy | Another operation is running on the site. Wait for it to finish. |
409 | in_use | It is still in use, still being removed, or managed somewhere else. Read the message: wait for the removal, remove what uses it first, or remove it where the message says. |
409 | managed_elsewhere | This site is read-only here. Change it in the control panel that manages it. |
409 | ssh_key_duplicate | The key is already added here. Use the existing one. |
422 | invalid | Fix the field named in field; errors says why. |
429 | rate_limited | Wait for the seconds in Retry-After. |
429 | ssh_throttled | Too many SSH key changes — try again in a minute. |
502 | none | Read the message; it says what happened. |
503 | none | Try again shortly. |
Reasons are listed by name in Errors and refusals.
The same task elsewhere
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/access/users/3418/keys \
-H "Authorization: Bearer $COREFINITY_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey6 supplier@desktop",
"name": "Supplier desktop"
}'use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('COREFINITY_TOKEN'))
->acceptJson()
->post('https://manage.corefinity.com/api/corestack/sites/1042/access/users/3418/keys', [
'key' => 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey6 supplier@desktop',
'name' => 'Supplier desktop',
]);
$data = $response->json();const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/access/users/3418/keys', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
key: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey6 supplier@desktop',
name: 'Supplier desktop',
}),
});
// 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/corestack/sites/1042/access/users/3418/keys",
headers={
"Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
"Accept": "application/json",
},
json={
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey6 supplier@desktop",
"name": "Supplier desktop",
},
)
data = res.json() if res.content else None{
"key": {
"added_at": "2026-11-05T09:16:40+00:00",
"added_by": {
"id": 2011,
"name": "Maya Okafor"
},
"bits": null,
"can_delete": true,
"comment": "supplier@desktop",
"company_key_id": null,
"fingerprint": "SHA256:oQwAERONEv3/COhZ7GWPxEIkoR6bRrONqBuTfNZJHBs",
"id": 7313,
"name": "Supplier desktop",
"restricted": false,
"restrictions": [],
"source": "user",
"status": "pending",
"status_label": "Applying",
"type": "ssh-ed25519"
},
"operation": {
"applied_at": null,
"can_retry": false,
"cluster": {
"id": 17,
"name": "WordPress Cluster 1"
},
"committed_at": "2026-11-05T09:16:40Z",
"completed_at": null,
"created_at": "2026-11-05T09:16:40Z",
"environment": {
"env_id": "rs-northwind-harbourandfinch-example-com",
"hostname": "harbourandfinch-example-com.northwind.cfstack.example.net",
"id": 1042,
"name": "Production",
"role": "production",
"role_label": "Production",
"slug": "production"
},
"error": null,
"failure_reason": null,
"from_version": null,
"hot": true,
"id": 146,
"install": null,
"label": "Picked up by the platform",
"notes": [],
"parent_operation_id": null,
"requested_by": {
"id": 2011,
"name": "Maya Okafor"
},
"reset_target": null,
"result": null,
"result_state": "none",
"retried_by_operation_id": null,
"retries_operation_id": null,
"retry_requires": null,
"revealed": null,
"scope": "site",
"site": {
"domain": "harbourandfinch.example.com",
"id": 1042
},
"status": "committed",
"status_label": "Waiting for the platform",
"step": "applied",
"steps": [
{
"key": "saved",
"label": "Saved",
"state": "done"
},
{
"key": "applied",
"label": "Picked up by the platform",
"state": "current"
},
{
"key": "live",
"label": "Live",
"state": "todo"
}
],
"subject": null,
"summary": "Add key \"Supplier desktop\" to supplier",
"to_version": null,
"type": "keys_change",
"type_label": "SSH keys"
}
}{
"message": "Unauthenticated."
}{
"code": "company_unavailable",
"message": "Your company is unavailable.",
"reason": "company_unavailable"
}{
"code": "feature_off",
"message": "Not found.",
"reason": "feature_off"
}{
"code": "busy",
"message": "Another change to this site is in progress. Wait for it to finish.",
"reason": "busy"
}{
"code": "invalid",
"errors": {
"key": [
"The key field is required."
]
},
"field": "key",
"message": "The key field is required.",
"reason": "invalid"
}{
"code": "rate_limited",
"message": "Too many requests. Try again in 60 seconds.",
"reason": "rate_limited",
"retry_after_seconds": 60
}{
"message": "The platform could not be reached. Try again in a minute."
}{
"message": "The platform deploy key is not configured. Contact support."
}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.