---
title: "corestack_ssh_key_add"
url: https://docs.corefinity.com/mcp/tools/corestack_ssh_key_add
type: tool
last_updated: 2026-11-13
feature: ssh-keys
related:
  - https://docs.corefinity.com/api/reference/access/create-ssh-key.md
  - https://docs.corefinity.com/guides/sites/access-and-security/ssh-keys.md
---
# corestack_ssh_key_add

**Add an SSH public key.** Adds an SSH public key; owner says where and which username it logs in as. Scope: write. Long-running: answers with a task.

- Scope: `write`
- Runs as a task: yes

## When to use it

Add an SSH public key. `owner` says where: an environment, website or company (it logs in as the shared `web` user) or `user` with your own id (it logs in as your own username everywhere you have access). Long-running: completes once every environment it reaches has the key.

## Inputs

- `owner` (object, required): `{type, id}` — `type` is `environment`, `website`, `company` or `user`.
- `public_key` (string, required): one OpenSSH line, or a PEM, RFC 4716 or PKCS#1 public key (converted). Never a private key.
- `name` (string, required): at most 100 characters.
- `applies_to` (object): company and website keys only — `{mode: all}` or `{mode: selected, environment_ids}`.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "applies_to": {
      "additionalProperties": false,
      "description": "Company and website keys only: all environments (default), or selected ones (environment_ids, at least one).",
      "properties": {
        "environment_ids": {
          "items": {
            "minimum": 1,
            "type": "integer"
          },
          "maxItems": 500,
          "type": "array"
        },
        "mode": {
          "enum": [
            "all",
            "selected"
          ],
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "type": "object"
    },
    "name": {
      "description": "A name you will recognise the key by (at most 100 characters).",
      "maxLength": 100,
      "minLength": 1,
      "type": "string"
    },
    "owner": {
      "additionalProperties": false,
      "description": "Where the key is added: an environment, a website or a company (it logs in as the shared web user), or user — your own user id — to log in as your own username everywhere you have access.",
      "properties": {
        "id": {
          "minimum": 1,
          "type": "integer"
        },
        "type": {
          "enum": [
            "environment",
            "website",
            "company",
            "user"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "id"
      ],
      "type": "object"
    },
    "public_key": {
      "description": "The PUBLIC key: one OpenSSH line (ssh-ed25519 AAAA… comment), or a PEM, RFC 4716 or PKCS#1 public key, which is converted. Never paste a private key.",
      "maxLength": 20000,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "owner",
    "public_key",
    "name"
  ],
  "type": "object"
}
```

## Refusals

- `managed_elsewhere` (message: "This site is managed by another control panel"): another control panel manages this site, so use that control panel for it. This is refused before anything else about the site, as in the Control Panel and the API. Nothing was done.
- `forbidden`: an `owner` of type `company` and the person's role lacks the Create Company SSH Keys permission
  (environment, website and personal keys do not ask it). The message names it and says an owner of the company can
  grant it in Roles; `details.permission` is `createCompanySSHKeys`. Nothing is changed.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).
- `tenant_mismatch` also answers the environment or website of a purged site (removed, or a create that failed and was rolled back), and `invalid_arguments` (`applies_to`) a selection naming that environment: its SSH access ended with it.
- `switched_off`: SSH keys are not switched on for this object yet.
- `ssh_key_invalid`: not one public key of an accepted type.
- `ssh_key_weak`: DSA, or RSA under 3072 bits.
- `ssh_private_key_refused`: a private key was pasted; it is never stored or echoed.
- `ssh_key_duplicate`: the same key is already there.
- `ssh_staff_key_refused`: the key is on Corefinity's list of staff and system keys, so it cannot be added anywhere, by anyone. No key was added. Corefinity staff can see the refused attempt (by its fingerprint, never the key itself), so if it is the person's own key, Corefinity support can check the list.
- `ssh_cap_exceeded`: too many keys; the refusal names the environment.
- `ssh_options_refused`: the line carries options.
- `ssh_key_type_unsupported`: security keys (`sk-*`) are not supported yet.
- `ssh_managed_on_another_environment`: this CoreStack Enterprise environment runs on the same server as another environment whose SSH the Control Panel manages, so its own keys are added, changed and removed there; the refusal's `managed_on` names that environment (`{id, name}`).
- `enterprise_panel_only`: SSH keys for CoreStack Enterprise environments are managed in the Control Panel only at the moment.

## Example

```json
{
  "name": "corestack_ssh_key_add",
  "arguments": {
    "owner": {
      "type": "company",
      "id": 4211
    },
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl ci@example",
    "name": "Bitbucket Pipelines"
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_ssh_key_add with owner {"type":"company","id":4211}, public_key ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl ci@example, name Bitbucket Pipelines. (Add an SSH public key.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/ssh/keys](https://docs.corefinity.com/api/reference/access/create-ssh-key.md)
- Guide: [SSH keys](https://docs.corefinity.com/guides/sites/access-and-security/ssh-keys.md)
