# Manage key pairs

Create or import the SSH key pairs you log in to instances with, and delete one no instance names.

A key pair is an SSH public key. Chosen at launch, it is installed on the machine at first boot.
**Compute → Key pairs** is the one list of key pairs: the launch form, launch templates and auto
scaling read the same pairs, and a pair has the same id in every API that names it.

## Prerequisites

- In the console: `kms:GenerateSshKeyPair` to create, `kms:ImportSshKeyPair` to import,
  `kms:DeleteSshKeyPair` to delete.
- In the API and CLI below: `ec2:ImportKeyPair` to import, `ec2:DeleteKeyPair` to delete.
- Room in the SSH key pairs quota.
- In the console, also `kms:ListSshKeyPairs` or `ec2:DescribeKeyPairs` to open **Key pairs**
  (without either, the page says **Access denied**).

## Create or import a key pair

**Console**
1. Open **Compute**, then **Key pairs**.
2. To have a key made: choose **Create key pair**, enter a **Name**, and choose **Generate**. The
   console makes an Ed25519 key in your browser (a browser without Ed25519 support has the
   platform make it).
3. In **Save private key**, choose **Copy** or **Download**, select **I have saved the private key
   in a secure location and understand it cannot be retrieved again.**, and choose **Done**. The
   private key is shown once and never again.

To register a key you already hold instead: choose **Import public key**, enter a **Name** and the
**Public key**, and choose **Import**.

You can do the same from the **Login key pair** picker of the launch form.

**CLI**
```sh
dcloud ec2 key-pairs import --name laptop --public-key "$(cat ~/.ssh/id_ed25519.pub)"
```

**API**
```http
POST /ec2/api/key-pairs
{ "name": "laptop", "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPL jane.doe@example.com" }
```

**Terraform**
```hcl
resource "dcloud_key_pair" "laptop" {
  name       = "laptop"
  public_key = file("~/.ssh/id_ed25519.pub")
}
```

The public key is one OpenSSH line, `<type> <base64> [comment]`, of type `ssh-ed25519`, `ssh-rsa`,
`ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384` or `ecdsa-sha2-nistp521`; anything else is refused
with `400` "Invalid SSH public key format". The answer holds its `fingerprint` (`SHA256:…`).

At launch, pass the pair's id as `sshKeyPairId` (or `keyPairId`; giving both is refused with "Give
sshKeyPairId or keyPairId, not both"). Without a key pair, no key is installed; on a machine where
Connect is connected you can add one later through Connect.

## Delete a key pair

**Console**
1. Open **Compute**, then **Key pairs**.
2. In the pair's row menu, choose **Delete key pair**.
3. Type the pair's name where the dialog asks for it, and choose **Delete**.

**CLI**
```sh
dcloud ec2 key-pairs delete key-pair-uuid
```

**API**
```http
DELETE /ec2/api/key-pairs/3f0c2a8e-0000-4000-8000-000000000001
```

**Terraform**
Remove the `dcloud_key_pair` resource and run `terraform apply`.

New instances can no longer be launched with the pair. Machines that already have the public key
keep it in `authorized_keys`: whoever holds the private key can still sign in there until you remove
the line on each machine.

Through the API and CLI, the delete is refused with `409` while an instance that is not terminated
still names the pair; the message names up to three of them ("… is still the key pair of 2
instances (…). Terminate them, or launch replacements with another key, before deleting it."). If
the provider refuses to remove a key it holds, the delete answers `502` "The provider still holds
this key and refused to delete it: …" and the pair stays, so you can retry. The console's delete
does not make the in-use check.

## Related

- [Launch an instance](launch-an-instance.md)
- `ec2.key-pairs.import` · `dcloud ec2 key-pairs delete` · `dcloud_key_pair`
