open-vault/website/content/api-docs/secret/ssh.mdx

---
layout: api
page_title: SSH - Secrets Engines - HTTP API
description: This is the API documentation for the Vault SSH secrets engine.
---

# SSH Secrets Engine (API)

This is the API documentation for the Vault SSH secrets engine. For general
information about the usage and operation of the SSH secrets engine, please see
the [SSH documentation](/docs/secrets/ssh).

This documentation assumes the SSH secrets engine is enabled at the `/ssh` path
in Vault. Since it is possible to enable secrets engines at any location, please
update your API calls accordingly.

## Create/Update Key

This endpoint creates or updates a named key.

| Method | Path              |
| :----- | :---------------- |
| `POST` | `/ssh/keys/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key to create. This
  is part of the request URL.

- `key` `(string: <required>)` – Specifies an SSH private key with appropriate
  privileges on remote hosts.

### Sample Payload

```json
{
  "key": "..."
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/keys/my-key
```

## Delete Key

This endpoint deletes a named key.

| Method   | Path              |
| :------- | :---------------- |
| `DELETE` | `/ssh/keys/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key to delete. This
  is part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/keys/my-key
```

## Create Role

This endpoint creates or updates a named role.

| Method | Path               |
| :----- | :----------------- |
| `POST` | `/ssh/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create. This
  is part of the request URL.

- `key` `(string: "")` – Specifies the name of the registered key in Vault.
  Before creating the role, use the `keys/` endpoint to create a named key. This
  is required for "Dynamic Key" type.

- `admin_user` `(string: "")` – Specifies the admin user at remote host. The
  shared key being registered should be for this user and should have root or
  sudo privileges. Every time a dynamic credential is generated for a client,
  Vault uses this admin username to login to remote host and install the
  generated credential. This is required for Dynamic Key type.

- `default_user` `(string: "")` – Specifies the default username for which a
  credential will be generated. When the endpoint `creds/` is used without a
  username, this value will be used as default username. Its recommended to
  create individual roles for each username to ensure absolute isolation between
  usernames. This is required for Dynamic Key type and OTP type.

  For the CA type, if you wish this to be a valid principal, it must also be
  in `allowed_users`.

- `cidr_list` `(string: "")` – Specifies a comma separated list of CIDR blocks
  for which the role is applicable for. It is possible that a same set of CIDR
  blocks are part of multiple roles. This is a required parameter, unless the
  role is registered under the `/config/zeroaddress` endpoint. Note: 
  [Not applicable for CA type]

- `exclude_cidr_list` `(string: "")` – Specifies a comma-separated list of CIDR
  blocks. IP addresses belonging to these blocks are not accepted by the role.
  This is particularly useful when big CIDR blocks are being used by the role
  and certain parts need to be kept out. Note: 
  [Not applicable for CA type]

- `port` `(int: 22)` – Specifies the port number for SSH connection. Port number
  does not play any role in OTP generation. For the `otp` secrets engine type, this is
  just a way to inform the client about the port number to use. The port number
  will be returned to the client by Vault along with the OTP.

- `key_type` `(string: <required>)` – Specifies the type of credentials
  generated by this role. This can be either `otp`, `dynamic` or `ca`.

- `key_bits` `(int: 1024)` – Specifies the length of the RSA dynamic key in
  bits. This can be either 1024 or 2048.

- `install_script` `(string: "")` – Specifies the script used to install and
  uninstall public keys in the target machine. Defaults to the built-in script.

- `allowed_users` `(string: "")` – If this option is not specified, or if it is
  `*`, the client can request a credential for any valid user at the remote
  host, including the admin user. If only certain usernames are to be allowed,
  then this list enforces it. If this field is set, then credentials can only
  be created for `default_user` and usernames present in this list. Setting
  this option will enable all the users with access this role to fetch
  credentials for all other usernames in this list.
  When `allowed_users_template` is set to `true`, this field can contain an identity
  template with any prefix or suffix, like `ssh-{{identity.entity.id}}-user`.
  Use with caution. N.B.: if the type is `ca`, an empty list does not allow any user;
  instead you must use `*` to enable this behavior.

- `allowed_users_template` `(bool: false)` - If set, allowed_users can be specified
  using identity template policies. Non-templated users are also permitted.

- `allowed_domains` `(string: "")` – The list of domains for which a client can
  request a host certificate. If this option is explicitly set to `"*"`, then
  credentials can be created for any domain. See also `allow_bare_domains` and
  `allow_subdomains`.

- `key_option_specs` `(string: "")` – Specifies a comma separated option
  specification which will be prefixed to RSA keys in the remote host's
  authorized_keys file. N.B.: Vault does not check this string for validity.

- `ttl` `(string: "")` – Specifies the Time To Live value provided as a string
  duration with time suffix. Hour is the largest suffix. If not set, uses the
  system default value or the value of `max_ttl`, whichever is shorter.

- `max_ttl` `(string: "")` – Specifies the maximum Time To Live provided as a
  string duration with time suffix. Hour is the largest suffix. If not set,
  defaults to the system maximum lease TTL.

- `allowed_critical_options` `(string: "")` – Specifies a comma-separated list
  of critical options that certificates can have when signed. To allow any
  critical options, set this to an empty string. Will default to allowing any
  critical options.

- `allowed_extensions` `(string: "")` – Specifies a comma-separated list of
  extensions that certificates can have when signed. To allow a user to specify
  any extension, set this to `"*"`. If not set, users will not be allowed to
  specify extensions and will get the extensions specified within `default_extensions`.
  For the list of extensions, take a look at the [sshd
  manual's](https://man.openbsd.org/sshd#AUTHORIZED_KEYS_FILE_FORMAT)
  `AUTHORIZED_KEYS FILE FORMAT` section. You should add a `permit-` before the
  name of extension to allow it.

- `default_critical_options` `(map<string|string>: "")` – Specifies a map of
  critical options certificates should have if none are provided when signing.
  This field takes in key value pairs in JSON format. Note that these are not
  restricted by `allowed_critical_options`. Defaults to none.

- `default_extensions` `(map<string|string>: "")` – Specifies a map of
  extensions certificates should have if none are provided when signing. This
  field takes in key value pairs in JSON format. Note that these are not
  restricted by `allowed_extensions`. Defaults to none.

- `allow_user_certificates` `(bool: false)` – Specifies if certificates are
  allowed to be signed for use as a 'user'.

- `allow_host_certificates` `(bool: false)` – Specifies if certificates are
  allowed to be signed for use as a 'host'.

- `allow_bare_domains` `(bool: false)` – Specifies if host certificates that are
  requested are allowed to use the base domains listed in `allowed_domains`, e.g.
  "example.com". This is a separate option as in some cases this can be
  considered a security threat.

- `allow_subdomains` `(bool: false)` – Specifies if host certificates that are
  requested are allowed to be subdomains of those listed in `allowed_domains`,
  e.g. if "example.com" is part of `allowed_domains`, this allows
  "foo.example.com".

- `allow_user_key_ids` `(bool: false)` – Specifies if users can override the key
  ID for a signed certificate with the "key_id" field. When false, the key ID
  will always be the token display name. The key ID is logged by the SSH server
  and can be useful for auditing.

- `key_id_format` `(string: "")` – When supplied, this value specifies a custom
  format for the key id of a signed certificate. The following variables are
  available for use: '{{token_display_name}}' - The display name of the token used
  to make the request. '{{role_name}}' - The name of the role signing the request.
  '{{public_key_hash}}' - A SHA256 checksum of the public key that is being signed.
  e.g. "custom-keyid-{{token_display_name}}"

- `allowed_user_key_lengths` `(map<string|(int|[]int|string)>: "")` – Specifies a
  map of ssh key types and their expected sizes which are allowed to be signed by
  the CA type. To specify multiple sizes, either use a comma-separated list or an
  array of allowed key widths. We support both OpenSSH-style key identifiers and
  short names (`rsa`, `ecdsa`, `dsa`, or `ed25519`) as keys. For example, a valid
  policy to allow common RSA and ECDSA key lengths might be:

  ```
  {
    "rsa": [2048, 3072, 4096],
    "ec": 256,
    "ecdsa-sha2-nistp521": 0
  }
  ```

  Note that when an algorithm identifier uniquely specifies a key length (such as
  with `ecdsa-sha2-nistp256` or `ed25519`), the value of the length is ignored (and
  can be zero).

  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
     and thus should not be used: `ed25519`.

- `algorithm_signer` `(string: "default")` - Algorithm to sign keys with. Valid
  values are `ssh-rsa`, `rsa-sha2-256`, `rsa-sha2-512`, or `default`. This
  value may also be left blank to use the signer's default algorithm, and must
  be left blank or have value `default` for CA key types other than RSA.

  ~> **Note**: The value of `default` may change over time as vulnerabilities
  in algorithms are discovered. The present value for RSA keys is equivalent
  to `rsa-sha2-256`.

  ~> **Warning**: The `algorithm_signer` value `ssh-rsa` uses the SHA-1 hash
  algorithm. This algorithm is now considered insecure and is not supported by
  current OpenSSH versions. As a result, Vault has made the new default
  `rsa-sha2-256` for RSA CA keys. It is strongly encouraged for all users to
  migrate to `rsa-sha2-256` or `default` if the role was created with an
  explicit `algorithm_signer=rsa-sha` parameter or has been migrated to such.

### Sample Payload

```json
{
  "key_type": "otp"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/roles/my-role
```

## Read Role

This endpoint queries a named role.

| Method | Path               |
| :----- | :----------------- |
| `GET`  | `/ssh/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to read. This
  is part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/roles/my-role
```

### Sample Response

For a dynamic key role:

```json
{
  "admin_user": "username",
  "cidr_list": "x.x.x.x/y",
  "default_user": "username",
  "key": "<key name>",
  "key_type": "dynamic",
  "port": 22
}
```

For an OTP role:

```json
{
  "cidr_list": "x.x.x.x/y",
  "default_user": "username",
  "key_type": "otp",
  "port": 22
}
```

For a CA role:

```json
{
  "allow_bare_domains": false,
  "allow_host_certificates": true,
  "allow_subdomains": false,
  "allow_user_key_ids": false,
  "allow_user_certificates": true,
  "allowed_critical_options": "",
  "allowed_extensions": "",
  "default_critical_options": {},
  "default_extensions": {},
  "max_ttl": "768h",
  "ttl": "4h"
}
```

## List Roles

This endpoint returns a list of available roles. Only the role names are
returned, not any values.

| Method | Path         |
| :----- | :----------- |
| `LIST` | `/ssh/roles` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/ssh/roles
```

### Sample Response

```json
{
  "auth": null,
  "data": {
    "keys": ["dev", "prod"],
    "key_info": {
      "dev": {
        "key_type": "ca"
      },
      "prod": {
        "key_type": "dynamic"
      }
    }
  },
  "lease_duration": 2764800,
  "lease_id": "",
  "renewable": false
}
```

## Delete Role

This endpoint deletes a named role.

| Method   | Path               |
| :------- | :----------------- |
| `DELETE` | `/ssh/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to delete. This
  is part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/roles/my-role
```

## List Zero-Address Roles

This endpoint returns the list of configured zero-address roles.

| Method | Path                      |
| :----- | :------------------------ |
| `GET`  | `/ssh/config/zeroaddress` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/config/zeroaddress
```

### Sample Response

```json
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "roles": ["otp_key_role"]
  },
  "warnings": null,
  "auth": null
}
```

## Configure Zero-Address Roles

This endpoint configures zero-address roles.

| Method | Path                      |
| :----- | :------------------------ |
| `POST` | `/ssh/config/zeroaddress` |

### Parameters

- `roles` `(string: <required>)` – Specifies a string containing comma separated
  list of role names which allows credentials to be requested for any IP
  address. CIDR blocks previously registered under these roles will be ignored.

### Sample Payload

```json
{
  "roles": ["otp_key_role"]
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/config/zeroaddress
```

## Delete Zero-Address Role

This endpoint deletes the zero-address roles configuration.

| Method   | Path                      |
| :------- | :------------------------ |
| `DELETE` | `/ssh/config/zeroaddress` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/config/zeroaddress
```

## Generate SSH Credentials

This endpoint creates credentials for a specific username and IP with the
parameters defined in the given role.

| Method | Path               |
| :----- | :----------------- |
| `POST` | `/ssh/creds/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create
  credentials against. This is part of the request URL.

- `username` `(string: "")` – Specifies the username on the remote host.

- `ip` `(string: <required>)` – Specifies the IP of the remote host.

### Sample Payload

```json
{
  "ip": "1.2.3.4"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/creds/my-role
```

### Sample Response

For a dynamic key role:

```json
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "admin_user": "rajanadar",
    "allowed_users": "",
    "cidr_list": "x.x.x.x/y",
    "default_user": "rajanadar",
    "exclude_cidr_list": "x.x.x.x/y",
    "install_script": "pretty_large_script",
    "key": "5d9ee6a1-c787-47a9-9738-da243f4f69bf",
    "key_bits": 1024,
    "key_option_specs": "",
    "key_type": "dynamic",
    "port": 22
  },
  "warnings": null,
  "auth": null
}
```

For an OTP role:

```json
{
  "lease_id": "sshs/creds/c3c2e60c-5a48-415a-9d5a-a41e0e6cdec5/3ee6ad28-383f-d482-2427-70498eba4d96",
  "renewable": false,
  "lease_duration": 2764800,
  "data": {
    "ip": "127.0.0.1",
    "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2",
    "key_type": "otp",
    "port": 22,
    "username": "rajanadar"
  },
  "warnings": null,
  "auth": null
}
```

## List Roles by IP

This endpoint lists all of the roles with which the given IP is associated.

| Method | Path          |
| :----- | :------------ |
| `POST` | `/ssh/lookup` |

### Parameters

- `ip` `(string: <required>)` – Specifies the IP of the remote host.

### Sample Payload

```json
{
  "ip": "1.2.3.4"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/lookup
```

### Sample Response

An array of roles as a secret structure.

```json
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "roles": [
      "fe6f61b7-7e4a-46a6-b2c8-0d530b8513df",
      "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"
    ]
  },
  "warnings": null,
  "auth": null
}
```

## Verify SSH OTP

This endpoint verifies if the given OTP is valid. This is an unauthenticated
endpoint.

| Method | Path          |
| :----- | :------------ |
| `POST` | `/ssh/verify` |

### Parameters

- `otp` `(string: <required>)` – Specifies the One-Time-Key that needs to be
  validated.

### Sample Payload

```json
{
  "otp": "bad2b3-..."
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/verify
```

### Sample Response

```json
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ip": "127.0.0.1",
    "username": "rajanadar"
  },
  "warnings": null,
  "auth": null
}
```

## Submit CA Information

This endpoint allows submitting the CA information for the secrets engine via an SSH
key pair. _If you have already set a certificate and key, they will be
overridden._

| Method | Path             |
| :----- | :--------------- | -------------------------- |
| `POST` | `/ssh/config/ca` | `200/204 application/json` |

### Parameters

- `private_key` `(string: "")` – Specifies the private key part the SSH CA key
  pair; required if `generate_signing_key` is false.

- `public_key` `(string: "")` – Specifies the public key part of the SSH CA key
  pair; required if `generate_signing_key` is false.

- `generate_signing_key` `(bool: true)` – Specifies if Vault should generate
  the signing key pair internally. If `true`, an RSA key pair is generated, and
  the generated public key is returned so you can add it to your configuration.
  If `false`, then you must provide `private_key` and `public_key`, but these
  can be of any valid signing key type.

- `key_type` `(string: ssh-rsa)` - Specifies the desired key type for the
  generated SSH CA key when `generate_signing_key` is set to `true`. Valid
  values are OpenSSH key type identifiers (`ssh-rsa`, `ecdsa-sha2-nistp256`,
  `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, or `ssh-ed25519`) or an
  algorithm (`rsa`, `ec`, or `ed25519`).

  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
      and thus should not be used: `ed25519`.

- `key_bits` `(int: 0)` - Specifies the desired key bits for the generated SSH
  CA key when `generate_signing_key` is set to `true`. This is only used for
  variable length keys (such as `ssh-rsa`, where the value of `key_bits`
  specifies the size of the RSA key pair to generate; with the default `0`
  value resulting in a 4096-bit key) or when the `ec` algorithm is specified
  in `key_type` (where the value of `key_bits` identifies which NIST P-curve
  to use; `256`, `384`, or `521`, with the default `0` value resulting in a
  NIST P-256 key).

### Sample Payload

```json
{
  "generate_signing_key": true
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/config/ca
```

### Sample Response

This will return a `204` response if `generate_signing_key` was unset or false.

This will return a `200` response if `generate_signing_key` was true:

```json
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
  },
  "warnings": null
}
```

## Delete CA Information

This endpoint deletes the CA information for the backend via an SSH key pair.

| Method   | Path             |
| :------- | :--------------- |
| `DELETE` | `/ssh/config/ca` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/config/ca
```

## Read Public Key (Unauthenticated)

This endpoint returns the configured/generated public key. This is an unauthenticated
endpoint.

| Method | Path              |
| :----- | :---------------- | ---------------- |
| `GET`  | `/ssh/public_key` | `200 text/plain` |

### Sample Request

```shell-session
$ curl http://127.0.0.1:8200/v1/ssh/public_key
```

### Sample Response

```text
    ssh-rsa AAAAHHNzaC1y...
```

## Read Public Key (Authenticated)

This endpoint reads the configured/generated public key.

| Method | Path             |
| :----- | :--------------- |
| `GET`  | `/ssh/config/ca` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/config/ca
```

### Sample Response

```json
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
  },
  "warnings": null
}
```

## Sign SSH Key

This endpoint signs an SSH public key based on the supplied parameters, subject
to the restrictions contained in the role named in the endpoint.

| Method | Path              |
| :----- | :---------------- |
| `POST` | `/ssh/sign/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to sign. This
  is part of the request URL.

- `public_key` `(string: <required>)` – Specifies the SSH public key that should
  be signed.

- `ttl` `(string: "")` – Specifies the Requested Time To Live. Cannot be greater
  than the role's `max_ttl` value. If not provided, the role's `ttl` value will
  be used. Note that the role values default to system values if not explicitly
  set.

- `valid_principals` `(string: "")` – Specifies valid principals, either
  usernames or hostnames, that the certificate should be signed for.

- `cert_type` `(string: "user")` – Specifies the type of certificate to be
  created; either "user" or "host".

- `key_id` `(string: "")` – Specifies the key id that the created certificate
  should have. If not specified, the display name of the token will be used.

- `critical_options` `(map<string|string>: "")` – Specifies a map of the
  critical options that the certificate should be signed for. Defaults to none.

- `extensions` `(map<string|string>: "")` – Specifies a map of the extensions
  that the certificate should be signed for. Defaults to none.

- `not_before_duration` `(duration: "30s")` – Specifies the duration by which to backdate the `ValidAfter` property.

### Sample Payload

```json
{
  "public_key": "ssh-rsa ..."
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/sign/my-key
```

### Sample Response

```json
{
  "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993",
  "renewable": false,
  "lease_duration": 21600,
  "data": {
    "serial_number": "f65ed2fd21443d5c",
    "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n"
  },
  "auth": null
}
```