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 '{"description":"personal server","principals":["inconshreveable.com","10.2.42.9"],"public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com","ssh_certificate_authority_id":"sshca_2gsqMGGXvYM8DeJYvNR8A8X4HRh","valid_until":"2024-08-21T20:36:22Z"}' \
https://api.ngrok.com/ssh_host_certificates

Parameters

NameTypeDescription
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

{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMV6XS+MXyDfK5tCPzze3jjPXCC1kBmhJGPRNmfd1BgwAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMmdzcU1FeUdRejExV1RUandBbkl6YzdtTmZHAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABmT6jGAAAAAGbGT8YAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJflP6DJZxfsES+eE2ouAo61KZLirldisNb4fF5nBC01AAAAUwAAAAtzc2gtZWQyNTUxOQAAAED9xFTelSJaiDrO4v9o4uptNdOTKjkn4bj1UA9+nFAjz1aMvmzid+rGy6Q60cRBCXZ6a5xKPRzFtXhfwL9j3sEE shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"created_at": "2024-05-23T20:36:22Z",
"description": "personal server",
"id": "shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"key_type": "ecdsa",
"principals": ["inconshreveable.com", "10.2.42.9"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
"ssh_certificate_authority_id": "sshca_2gsqMGGXvYM8DeJYvNR8A8X4HRh",
"uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"valid_after": "2024-05-23T20:36:22Z",
"valid_until": "2024-08-21T20:36:22Z"
}

Fields

NameTypeDescription
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_2gsqMEyGQz11WTTjwAnIzc7mNfG

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_2gsqMEyGQz11WTTjwAnIzc7mNfG

Response

Returns a 200 response on success

Example Response

{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMV6XS+MXyDfK5tCPzze3jjPXCC1kBmhJGPRNmfd1BgwAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMmdzcU1FeUdRejExV1RUandBbkl6YzdtTmZHAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABmT6jGAAAAAGbGT8YAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJflP6DJZxfsES+eE2ouAo61KZLirldisNb4fF5nBC01AAAAUwAAAAtzc2gtZWQyNTUxOQAAAED9xFTelSJaiDrO4v9o4uptNdOTKjkn4bj1UA9+nFAjz1aMvmzid+rGy6Q60cRBCXZ6a5xKPRzFtXhfwL9j3sEE shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"created_at": "2024-05-23T20:36:22Z",
"description": "personal server",
"id": "shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"key_type": "ecdsa",
"metadata": "{\"region\": \"us-west-2\"}",
"principals": ["inconshreveable.com", "10.2.42.9"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
"ssh_certificate_authority_id": "sshca_2gsqMGGXvYM8DeJYvNR8A8X4HRh",
"uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"valid_after": "2024-05-23T20:36:22Z",
"valid_until": "2024-08-21T20:36:22Z"
}

Fields

NameTypeDescription
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

{
"next_page_uri": null,
"ssh_host_certificates": [
{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMV6XS+MXyDfK5tCPzze3jjPXCC1kBmhJGPRNmfd1BgwAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMmdzcU1FeUdRejExV1RUandBbkl6YzdtTmZHAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABmT6jGAAAAAGbGT8YAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJflP6DJZxfsES+eE2ouAo61KZLirldisNb4fF5nBC01AAAAUwAAAAtzc2gtZWQyNTUxOQAAAED9xFTelSJaiDrO4v9o4uptNdOTKjkn4bj1UA9+nFAjz1aMvmzid+rGy6Q60cRBCXZ6a5xKPRzFtXhfwL9j3sEE shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"created_at": "2024-05-23T20:36:22Z",
"description": "personal server",
"id": "shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"key_type": "ecdsa",
"principals": ["inconshreveable.com", "10.2.42.9"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
"ssh_certificate_authority_id": "sshca_2gsqMGGXvYM8DeJYvNR8A8X4HRh",
"uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"valid_after": "2024-05-23T20:36:22Z",
"valid_until": "2024-08-21T20:36:22Z"
}
],
"uri": "https://api.ngrok.com/ssh_host_certificates"
}

Fields

NameTypeDescription
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

NameTypeDescription
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_2gsqMEyGQz11WTTjwAnIzc7mNfG

Parameters

NameTypeDescription
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

{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMV6XS+MXyDfK5tCPzze3jjPXCC1kBmhJGPRNmfd1BgwAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMmdzcU1FeUdRejExV1RUandBbkl6YzdtTmZHAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABmT6jGAAAAAGbGT8YAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJflP6DJZxfsES+eE2ouAo61KZLirldisNb4fF5nBC01AAAAUwAAAAtzc2gtZWQyNTUxOQAAAED9xFTelSJaiDrO4v9o4uptNdOTKjkn4bj1UA9+nFAjz1aMvmzid+rGy6Q60cRBCXZ6a5xKPRzFtXhfwL9j3sEE shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"created_at": "2024-05-23T20:36:22Z",
"description": "personal server",
"id": "shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"key_type": "ecdsa",
"metadata": "{\"region\": \"us-west-2\"}",
"principals": ["inconshreveable.com", "10.2.42.9"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
"ssh_certificate_authority_id": "sshca_2gsqMGGXvYM8DeJYvNR8A8X4HRh",
"uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_2gsqMEyGQz11WTTjwAnIzc7mNfG",
"valid_after": "2024-05-23T20:36:22Z",
"valid_until": "2024-08-21T20:36:22Z"
}

Fields

NameTypeDescription
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