Create an SSH or SFTP user
Adds a named user to the site or environment: ssh for SSH and SFTP over the whole site, or sftp for SFTP only, limited to one folder. A generated password is in this answer and nowhere else, so asking for one also needs the exec scope.
- Needs
execas well: The body asks for a generated password (passwordisgenerate).
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.
Body
A note to recognise the user by. Up to 60 characters.
none (the default) makes a user that signs in with keys only. set uses password_value. generate makes a password and answers it once; it also needs the exec scope.
generatesetnonenullThe password, with set, and needed then: 12 to 64 characters, not the username and not containing the site's domain. One that breaks these is refused on password_value.
For sftp users, the folder the user is limited to, inside htdocs or shared. Left out, it is htdocs. Not accepted for ssh users. At most 200 characters, with no / at either end; each part is letters, digits, dots, dashes and underscores.
ssh gives SSH and SFTP over the whole site. sftp gives SFTP only, inside root_path.
sshsftp3 to 31 lower-case letters, digits or dashes, starting with a letter. Some names are reserved.
Returns
201 The user was added and the change is being applied. Follow operation.id with GET /. password holds a generated password, once; the answer is sent with Cache-Control: no-store.
Fields of the 201 answer
The site's access with the new user in it. A site's or environment's SSH and SFTP access, as a change answers it.
Fields
Whether the saved users and keys are live on the site. Whether a saved set of rules is live on the site.
Fields
Sent only by the sets that have more to say, such as HTTP authentication.
The change that is applying the set, while one is running.
Such as applied or applying.
The company keys that can reach the site.
Fields of each item
Whether the key reaches this site.
Whether the company key applies to all of the company's sites or to selected ones.
allselectedAt least 1.
Where to connect.
Fields
The SSH host of the site's cluster. Empty while the site has none yet.
The site's or environment's own port.
The built-in user, web.
An ssh command that opens a tunnel to the database on 127.0.0.1:3306 of your machine.
Fields
Folders an SFTP user is often limited to on this kind of site.
The most named users a site can have.
Whether the browser terminal can be opened for the site.
Fields
The open terminal session on the site, when there is one, whoever opened it.
Fields
At least 1.
When the session started, in UTC with a +00:00 offset. Format: date-time.
Who opened the session. A session Corefinity support opened reads Corefinity support with a null id. A person by id and name. Corefinity staff read as Corefinity support with a null id.
Fields
Why not, in plain words.
The built-in web user first, then the named users.
Fields of each item
Fields
The ssh command. Null for an SFTP user.
The id the /access/users/{user} endpoints take.
The user's keys. While SSH keys are on for your company, web lists every key that can log in as it, from every level.
Fields of each item
Whether this endpoint group can remove the key. Other keys are removed where they were added.
The comment at the end of the key line, when it had one.
The SHA-256 fingerprint, as ssh-keygen -lf prints it.
The id DELETE / takes. 0 for the Corefinity deploy key.
Sent while SSH keys are on for your company. The level the key comes from.
Fields
agencycompanywebsiteenvironmentuserlegacysystemTrue when the key carries restrictions from before it was imported. Only Corefinity changes those.
company is a company key. system is the Corefinity deploy key. Everything else reads user.
usercompanysystempendingappliedfailedremovingThe key type, such as ssh-ed25519 or ssh-rsa.
built_in is web. It cannot be changed or removed.
built_innamedWhether the user has a password. The password itself is never answered here.
Fields
The folder an SFTP user is limited to, relative to the site.
The same folder as a path on the server.
pending until the change that made or changed the user is live.
pendingappliedfailedremovingsshsftpThe user's numeric id on the server.
A change the Control Panel is making or has made. A save or an action that starts work answers one in operation; read it again by id with GET / until status is completed or failed. Both answers have this shape; the few endpoints that answer a different one say so.
Fields
The cluster the operation runs on.
Why the operation failed, in plain words. Null unless status is failed.
A stable code for the failure.
True when the change applies without a maintenance window.
What the operation did differently on purpose. Empty when nothing.
Fields of each item
Who asked for the change.
Present on some site creations and copies.
Always null here. A one-time result is read once with the reveal endpoint.
nonependingavailableviewedWhat a retry needs first, if anything.
Who revealed a one-time result and when, when there was one.
siteclusterbatchThe website the operation belongs to. Null for a cluster's own operation.
Where a change is. completed and failed are final; every other status means the change is still running and blocks another change to the same site.
pendingcommittedrolling_outexecutingcompletedfailedThe key of the step the operation is at. Null once it has completed.
Fields of each item
One of done, current, todo, failed or skipped.
The kind of change, such as crons_change or redirects_change.
The generated password, or null when none was generated.
The built-in web user, or a named SSH or SFTP user.
Fields
Fields
The ssh command. Null for an SFTP user.
The id the /access/users/{user} endpoints take.
The user's keys. While SSH keys are on for your company, web lists every key that can log in as it, from every level.
Fields of each item
Whether this endpoint group can remove the key. Other keys are removed where they were added.
The comment at the end of the key line, when it had one.
The SHA-256 fingerprint, as ssh-keygen -lf prints it.
The id DELETE / takes. 0 for the Corefinity deploy key.
Sent while SSH keys are on for your company. The level the key comes from.
Fields
agencycompanywebsiteenvironmentuserlegacysystemTrue when the key carries restrictions from before it was imported. Only Corefinity changes those.
company is a company key. system is the Corefinity deploy key. Everything else reads user.
usercompanysystempendingappliedfailedremovingThe key type, such as ssh-ed25519 or ssh-rsa.
built_in is web. It cannot be changed or removed.
built_innamedWhether the user has a password. The password itself is never answered here.
Fields
The folder an SFTP user is limited to, relative to the site.
The same folder as a path on the server.
pending until the change that made or changed the user is live.
pendingappliedfailedremovingsshsftpThe user's numeric id on the server.
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. |
422 | ssh_person_managed_elsewhere | That username belongs to a person's own SSH login, managed in their profile. Choose another name. |
429 | rate_limited | Wait for the seconds in Retry-After. |
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 \
-H "Authorization: Bearer $COREFINITY_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"label": "Photographer",
"password": "generate",
"root_path": "htdocs/wp-content/uploads",
"type": "sftp",
"username": "photographer"
}'use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('COREFINITY_TOKEN'))
->acceptJson()
->post('https://manage.corefinity.com/api/corestack/sites/1042/access/users', [
'label' => 'Photographer',
'password' => 'generate',
'root_path' => 'htdocs/wp-content/uploads',
'type' => 'sftp',
'username' => 'photographer',
]);
$data = $response->json();const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/access/users', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
label: 'Photographer',
password: 'generate',
root_path: 'htdocs/wp-content/uploads',
type: 'sftp',
username: 'photographer',
}),
});
// 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",
headers={
"Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
"Accept": "application/json",
},
json={
"label": "Photographer",
"password": "generate",
"root_path": "htdocs/wp-content/uploads",
"type": "sftp",
"username": "photographer",
},
)
data = res.json() if res.content else None{
"access": {
"apply": {
"applied_at": "2026-11-03T10:03:10+00:00",
"error": null,
"operation": {
"id": 5120,
"scope": "site",
"status": "committed",
"status_label": "Waiting for the platform",
"summary": "Add SFTP user photographer",
"to_version": null,
"type": "users_change",
"type_label": "SSH / SFTP users"
},
"state": "applying",
"state_label": "Applying"
},
"company_keys": [],
"connection": {
"host": "ssh-northwind.example.net",
"port": 20101,
"ssh_user": "web",
"tunnel_command": "ssh -N -L 3306:127.0.0.1:3306 -p 20101 [email protected]"
},
"limits": {
"company_keys_max": 50,
"keys_per_user_max": 50,
"root_path_suggestions": [
"htdocs",
"htdocs/wp-content/uploads",
"shared"
],
"users_max": 25
},
"terminal": {
"active_session": null,
"available": true,
"reason": null
},
"users": [
{
"can_change": false,
"can_delete": false,
"connection": {
"command": "ssh -p 20101 [email protected]",
"sftp_command": "sftp -P 20101 [email protected]"
},
"created_at": "2026-11-02T10:15:00+00:00",
"created_by": null,
"id": 417,
"keys": [
{
"added_at": "2026-11-02T10:15:00+00:00",
"added_by": null,
"bits": 3072,
"can_delete": false,
"comment": "cfcp:deploy",
"company_key_id": null,
"fingerprint": "SHA256:ExampleDeployKeyFingerprintNotARealOne00000",
"id": 0,
"name": "cfcp-deploy",
"restricted": false,
"restrictions": [],
"source": "system",
"status": "applied",
"status_label": "Applied",
"type": "ssh-rsa"
}
],
"kind": "built_in",
"label": null,
"password": {
"set": false,
"set_at": null,
"set_by": null
},
"root_path": null,
"root_path_absolute": null,
"status": "applied",
"status_label": "Applied",
"type": "ssh",
"type_label": "SSH + SFTP",
"uid": 9991,
"username": "web"
},
{
"can_change": true,
"can_delete": true,
"connection": {
"command": null,
"sftp_command": "sftp -P 20101 [email protected]"
},
"created_at": "2026-11-05T09:16:40+00:00",
"created_by": {
"id": 2011,
"name": "Maya Okafor"
},
"id": 419,
"keys": [],
"kind": "named",
"label": "Photographer",
"password": {
"set": true,
"set_at": "2026-11-05T09:16:40+00:00",
"set_by": {
"id": 2011,
"name": "Maya Okafor"
}
},
"root_path": "htdocs/wp-content/uploads",
"root_path_absolute": "/var/www/harbourandfinch.example.com/htdocs/wp-content/uploads",
"status": "pending",
"status_label": "Applying",
"type": "sftp",
"type_label": "SFTP only",
"uid": 20002,
"username": "photographer"
},
{
"can_change": true,
"can_delete": true,
"connection": {
"command": "ssh -p 20101 [email protected]",
"sftp_command": "sftp -P 20101 [email protected]"
},
"created_at": "2026-11-02T10:15:00+00:00",
"created_by": {
"id": 2011,
"name": "Maya Okafor"
},
"id": 3418,
"keys": [
{
"added_at": "2026-11-03T10:02:44+00:00",
"added_by": null,
"bits": null,
"can_delete": true,
"comment": null,
"company_key_id": null,
"fingerprint": "SHA256:KhDfvkk2rdhCA9zaR3SurL80w/B/MbslK5FOxIaEpY0",
"id": 7312,
"name": "Supplier laptop",
"restricted": false,
"restrictions": [],
"source": "user",
"status": "applied",
"status_label": "Applied",
"type": "ssh-ed25519"
}
],
"kind": "named",
"label": "Print supplier",
"password": {
"set": false,
"set_at": null,
"set_by": null
},
"root_path": null,
"root_path_absolute": null,
"status": "applied",
"status_label": "Applied",
"type": "ssh",
"type_label": "SSH + SFTP",
"uid": 20001,
"username": "supplier"
}
]
},
"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": 5120,
"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 SFTP user photographer",
"to_version": null,
"type": "users_change",
"type_label": "SSH / SFTP users"
},
"password": {
"revealed_at": "2026-11-05T09:16:40+00:00",
"value": "ExamplePasswordAbc23"
},
"user": {
"can_change": true,
"can_delete": true,
"connection": {
"command": null,
"sftp_command": "sftp -P 20101 [email protected]"
},
"created_at": "2026-11-05T09:16:40+00:00",
"created_by": {
"id": 2011,
"name": "Maya Okafor"
},
"id": 419,
"keys": [],
"kind": "named",
"label": "Photographer",
"password": {
"set": true,
"set_at": "2026-11-05T09:16:40+00:00",
"set_by": {
"id": 2011,
"name": "Maya Okafor"
}
},
"root_path": "htdocs/wp-content/uploads",
"root_path_absolute": "/var/www/harbourandfinch.example.com/htdocs/wp-content/uploads",
"status": "pending",
"status_label": "Applying",
"type": "sftp",
"type_label": "SFTP only",
"uid": 20002,
"username": "photographer"
}
}{
"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",
"message": "This user cannot be changed",
"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 reveals a secret. Copy the request and run it yourself when you are sure.