Skip to main content

SSH Host Certificates

Create SSH Host Certificate​

Create a new SSH Host Certificate

Request​

POST /ssh_host_certificates

Example Request​

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"ssh_certificate_authority_id":"sshca_2TMGJ1PoNFZIej4eUV3wlwI8L0h","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com","principals":["inconshreveable.com","10.2.42.9"],"valid_until":"2023-10-29T23:17:40Z","description":"personal server"}' \
https://api.ngrok.com/ssh_host_certificates

Parameters​

   
ssh_certificate_authority_idstringthe ssh certificate authority that is used to sign this ssh host certificate
public_keystringa public key in OpenSSH Authorized Keys format that this certificate signs
principalsList<string>the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_afterstringThe time when the host certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified.
valid_untilstringThe time when this host certificate becomes invalid, in RFC 3339 format. If unspecified, a default value of one year in the future will be used. The OpenSSH certificates RFC calls this valid_before.
descriptionstringhuman-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

Response​

Returns a 201 response on success

Example Response​

{
    "id": "shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
    "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
    "created_at": "2023-07-31T23:17:40Z",
    "description": "personal server",
    "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
    "key_type": "ecdsa",
    "ssh_certificate_authority_id": "sshca_2TMGJ1PoNFZIej4eUV3wlwI8L0h",
    "principals": ["inconshreveable.com", "10.2.42.9"],
    "valid_after": "2023-07-31T23:17:40Z",
    "valid_until": "2023-10-29T23:17:40Z",
    "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgaoey/Kh2csL4+54OlMEo64X4PSBpchPgFW1fuQxwq5UAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMlRNR0oydUVPV1ZtbEwwbm1DeGtCZTM1QzJDAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABkyEEUAAAAAGU+6BQAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAII3hXmtlRapzL5QKuiJWcHboZMenhuJfg0ncveojaGQJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAtodB84aVHuP6B5vb9El0F5lLoCVfhAvoLubqDmGRuM2kSf/uLPzWZmmc1b8DNfo6fh3WgEdEFvO7rChA6T6gI shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C"
}

Fields​

   
idstringunique identifier for this SSH Host Certificate
uristringURI of the SSH Host Certificate API resource
created_atstringtimestamp when the SSH Host Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_keystringa public key in OpenSSH Authorized Keys format that this certificate signs
key_typestringthe key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_idstringthe ssh certificate authority that is used to sign this ssh host certificate
principalsList<string>the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_afterstringthe time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_untilstringthe time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificatestringthe signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

Delete SSH Host Certificate​

Delete an SSH Host Certificate

Request​

DELETE /ssh_host_certificates/{id}

Example Request​

curl \
-X DELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_host_certificates/shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C

Response​

Returns a 204 response with no body on success

Get SSH Host Certificate​

Get detailed information about an SSH Host Certficate

Request​

GET /ssh_host_certificates/{id}

Example Request​

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_host_certificates/shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C

Response​

Returns a 200 response on success

Example Response​

{
    "id": "shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
    "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
    "created_at": "2023-07-31T23:17:40Z",
    "description": "personal server",
    "metadata": "{\"region\": \"us-west-2\"}",
    "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
    "key_type": "ecdsa",
    "ssh_certificate_authority_id": "sshca_2TMGJ1PoNFZIej4eUV3wlwI8L0h",
    "principals": ["inconshreveable.com", "10.2.42.9"],
    "valid_after": "2023-07-31T23:17:40Z",
    "valid_until": "2023-10-29T23:17:40Z",
    "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgaoey/Kh2csL4+54OlMEo64X4PSBpchPgFW1fuQxwq5UAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMlRNR0oydUVPV1ZtbEwwbm1DeGtCZTM1QzJDAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABkyEEUAAAAAGU+6BQAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAII3hXmtlRapzL5QKuiJWcHboZMenhuJfg0ncveojaGQJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAtodB84aVHuP6B5vb9El0F5lLoCVfhAvoLubqDmGRuM2kSf/uLPzWZmmc1b8DNfo6fh3WgEdEFvO7rChA6T6gI shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C"
}

Fields​

   
idstringunique identifier for this SSH Host Certificate
uristringURI of the SSH Host Certificate API resource
created_atstringtimestamp when the SSH Host Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_keystringa public key in OpenSSH Authorized Keys format that this certificate signs
key_typestringthe key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_idstringthe ssh certificate authority that is used to sign this ssh host certificate
principalsList<string>the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_afterstringthe time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_untilstringthe time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificatestringthe signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

List SSH Host Certificates​

List all SSH Host Certificates issued on this account

Request​

GET /ssh_host_certificates

Example Request​

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_host_certificates

Response​

Returns a 200 response on success

Example Response​

{
    "ssh_host_certificates": [
        {
            "id": "shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
            "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
            "created_at": "2023-07-31T23:17:40Z",
            "description": "personal server",
            "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
            "key_type": "ecdsa",
            "ssh_certificate_authority_id": "sshca_2TMGJ1PoNFZIej4eUV3wlwI8L0h",
            "principals": ["inconshreveable.com", "10.2.42.9"],
            "valid_after": "2023-07-31T23:17:40Z",
            "valid_until": "2023-10-29T23:17:40Z",
            "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgaoey/Kh2csL4+54OlMEo64X4PSBpchPgFW1fuQxwq5UAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMlRNR0oydUVPV1ZtbEwwbm1DeGtCZTM1QzJDAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABkyEEUAAAAAGU+6BQAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAII3hXmtlRapzL5QKuiJWcHboZMenhuJfg0ncveojaGQJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAtodB84aVHuP6B5vb9El0F5lLoCVfhAvoLubqDmGRuM2kSf/uLPzWZmmc1b8DNfo6fh3WgEdEFvO7rChA6T6gI shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C"
        }
    ],
    "uri": "https://api.ngrok.com/ssh_host_certificates",
    "next_page_uri": null
}

Fields​

   
ssh_host_certificatesSSHHostCertificatethe list of all ssh host certificates on this account
uristringURI of the ssh host certificates list API resource
next_page_uristringURI of the next page, or null if there is no next page

SSHHostCertificate fields​

   
idstringunique identifier for this SSH Host Certificate
uristringURI of the SSH Host Certificate API resource
created_atstringtimestamp when the SSH Host Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_keystringa public key in OpenSSH Authorized Keys format that this certificate signs
key_typestringthe key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_idstringthe ssh certificate authority that is used to sign this ssh host certificate
principalsList<string>the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_afterstringthe time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_untilstringthe time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificatestringthe signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

Update SSH Host Certificate​

Update an SSH Host Certificate

Request​

PATCH /ssh_host_certificates/{id}

Example Request​

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"region\": \"us-west-2\"}"}' \
https://api.ngrok.com/ssh_host_certificates/shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C

Parameters​

   
idstring
descriptionstringhuman-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

Response​

Returns a 200 response on success

Example Response​

{
    "id": "shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
    "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C",
    "created_at": "2023-07-31T23:17:40Z",
    "description": "personal server",
    "metadata": "{\"region\": \"us-west-2\"}",
    "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
    "key_type": "ecdsa",
    "ssh_certificate_authority_id": "sshca_2TMGJ1PoNFZIej4eUV3wlwI8L0h",
    "principals": ["inconshreveable.com", "10.2.42.9"],
    "valid_after": "2023-07-31T23:17:40Z",
    "valid_until": "2023-10-29T23:17:40Z",
    "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgaoey/Kh2csL4+54OlMEo64X4PSBpchPgFW1fuQxwq5UAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMlRNR0oydUVPV1ZtbEwwbm1DeGtCZTM1QzJDAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABkyEEUAAAAAGU+6BQAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAII3hXmtlRapzL5QKuiJWcHboZMenhuJfg0ncveojaGQJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAtodB84aVHuP6B5vb9El0F5lLoCVfhAvoLubqDmGRuM2kSf/uLPzWZmmc1b8DNfo6fh3WgEdEFvO7rChA6T6gI shcrt_2TMGJ2uEOWVmlL0nmCxkBe35C2C"
}

Fields​

   
idstringunique identifier for this SSH Host Certificate
uristringURI of the SSH Host Certificate API resource
created_atstringtimestamp when the SSH Host Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_keystringa public key in OpenSSH Authorized Keys format that this certificate signs
key_typestringthe key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_idstringthe ssh certificate authority that is used to sign this ssh host certificate
principalsList<string>the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_afterstringthe time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_untilstringthe time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificatestringthe signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive