Skip to main content

SSH User Certificates

Create SSH User Certificate

Create a new SSH User Certificate

Request

POST /ssh_user_certificates

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"temporary access to staging machine","principals":["ec2-user","root"],"public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop","ssh_certificate_authority_id":"sshca_2k5okJyUQ003HCpCBByt1nOc8mh","valid_until":"2024-10-31T07:15:39Z"}' \
https://api.ngrok.com/ssh_user_certificates

Parameters

NameTypeDescription
ssh_certificate_authority_idstringthe ssh certificate authority that is used to sign this ssh user certificate
public_keystringa public key in OpenSSH Authorized Keys format that this certificate signs
principalsList<string>the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizing the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_optionsMap<string, string>A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensionsMap<string, string>A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
valid_afterstringThe time when the user 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 24 hours will be used. The OpenSSH certificates RFC calls this valid_before.
descriptionstringhuman-readable description of this SSH User Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

Response

Returns a 201 response on success

Example Response

{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgI1E4yNOw0TrjVFFWEk0Jz5Ob9RMf5qkgxZEuTbzo08IAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMms1b2tFNmFZNTZpQ0tjSXU4N2cwdXJYSHIxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGash5sAAAAAZyMumwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIC0czA7npWVB2L1CxSwDjypkaoxs/pia4cj8aSuOjfkRAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAnsas2cGZiLVvISAC/MLa1ExDz3AwJYmpwOeBAmrGf47xICPmARc3Ly7V42bu9IV7mEhquBH+eP3iuIVDOh6UJ sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"created_at": "2024-08-02T07:15:39Z",
"critical_options": {},
"description": "temporary access to staging machine",
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"id": "sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"key_type": "ecdsa",
"principals": ["ec2-user", "root"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"ssh_certificate_authority_id": "sshca_2k5okJyUQ003HCpCBByt1nOc8mh",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"valid_after": "2024-08-02T07:15:39Z",
"valid_until": "2024-10-31T07:15:39Z"
}

Fields

NameTypeDescription
idstringunique identifier for this SSH User Certificate
uristringURI of the SSH User Certificate API resource
created_atstringtimestamp when the SSH User Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH User Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH User 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 user certificate
principalsList<string>the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizing the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_optionsMap<string, string>A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensionsMap<string, string>A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
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 User Certificate

Delete an SSH User Certificate

Request

DELETE /ssh_user_certificates/{id}

Example Request

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

Response

Returns a 204 response with no body on success

Get SSH User Certificate

Get detailed information about an SSH User Certficate

Request

GET /ssh_user_certificates/{id}

Example Request

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

Response

Returns a 200 response on success

Example Response

{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgI1E4yNOw0TrjVFFWEk0Jz5Ob9RMf5qkgxZEuTbzo08IAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMms1b2tFNmFZNTZpQ0tjSXU4N2cwdXJYSHIxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGash5sAAAAAZyMumwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIC0czA7npWVB2L1CxSwDjypkaoxs/pia4cj8aSuOjfkRAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAnsas2cGZiLVvISAC/MLa1ExDz3AwJYmpwOeBAmrGf47xICPmARc3Ly7V42bu9IV7mEhquBH+eP3iuIVDOh6UJ sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"created_at": "2024-08-02T07:15:39Z",
"critical_options": {},
"description": "temporary access to staging machine for alan",
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"id": "sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"key_type": "ecdsa",
"metadata": "{\"user_email\": \"alan@example.com\"}",
"principals": ["ec2-user", "root"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"ssh_certificate_authority_id": "sshca_2k5okJyUQ003HCpCBByt1nOc8mh",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"valid_after": "2024-08-02T07:15:39Z",
"valid_until": "2024-10-31T07:15:39Z"
}

Fields

NameTypeDescription
idstringunique identifier for this SSH User Certificate
uristringURI of the SSH User Certificate API resource
created_atstringtimestamp when the SSH User Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH User Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH User 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 user certificate
principalsList<string>the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizing the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_optionsMap<string, string>A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensionsMap<string, string>A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
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 User Certificates

List all SSH User Certificates issued on this account

Request

GET /ssh_user_certificates

Example Request

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

Response

Returns a 200 response on success

Example Response

{
"next_page_uri": null,
"ssh_user_certificates": [
{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgI1E4yNOw0TrjVFFWEk0Jz5Ob9RMf5qkgxZEuTbzo08IAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMms1b2tFNmFZNTZpQ0tjSXU4N2cwdXJYSHIxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGash5sAAAAAZyMumwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIC0czA7npWVB2L1CxSwDjypkaoxs/pia4cj8aSuOjfkRAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAnsas2cGZiLVvISAC/MLa1ExDz3AwJYmpwOeBAmrGf47xICPmARc3Ly7V42bu9IV7mEhquBH+eP3iuIVDOh6UJ sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"created_at": "2024-08-02T07:15:39Z",
"critical_options": {},
"description": "temporary access to staging machine",
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"id": "sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"key_type": "ecdsa",
"principals": ["ec2-user", "root"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"ssh_certificate_authority_id": "sshca_2k5okJyUQ003HCpCBByt1nOc8mh",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"valid_after": "2024-08-02T07:15:39Z",
"valid_until": "2024-10-31T07:15:39Z"
}
],
"uri": "https://api.ngrok.com/ssh_user_certificates"
}

Fields

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

SSHUserCertificate fields

NameTypeDescription
idstringunique identifier for this SSH User Certificate
uristringURI of the SSH User Certificate API resource
created_atstringtimestamp when the SSH User Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH User Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH User 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 user certificate
principalsList<string>the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizing the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_optionsMap<string, string>A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensionsMap<string, string>A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
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 User Certificate

Update an SSH User Certificate

Request

PATCH /ssh_user_certificates/{id}

Example Request

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"temporary access to staging machine for alan","metadata":"{\"user_email\": \"alan@example.com\"}"}' \
https://api.ngrok.com/ssh_user_certificates/sucrt_2k5okE6aY56iCKcIu87g0urXHr1

Parameters

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

Response

Returns a 200 response on success

Example Response

{
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgI1E4yNOw0TrjVFFWEk0Jz5Ob9RMf5qkgxZEuTbzo08IAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMms1b2tFNmFZNTZpQ0tjSXU4N2cwdXJYSHIxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGash5sAAAAAZyMumwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIC0czA7npWVB2L1CxSwDjypkaoxs/pia4cj8aSuOjfkRAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAnsas2cGZiLVvISAC/MLa1ExDz3AwJYmpwOeBAmrGf47xICPmARc3Ly7V42bu9IV7mEhquBH+eP3iuIVDOh6UJ sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"created_at": "2024-08-02T07:15:39Z",
"critical_options": {},
"description": "temporary access to staging machine for alan",
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"id": "sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"key_type": "ecdsa",
"metadata": "{\"user_email\": \"alan@example.com\"}",
"principals": ["ec2-user", "root"],
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"ssh_certificate_authority_id": "sshca_2k5okJyUQ003HCpCBByt1nOc8mh",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2k5okE6aY56iCKcIu87g0urXHr1",
"valid_after": "2024-08-02T07:15:39Z",
"valid_until": "2024-10-31T07:15:39Z"
}

Fields

NameTypeDescription
idstringunique identifier for this SSH User Certificate
uristringURI of the SSH User Certificate API resource
created_atstringtimestamp when the SSH User Certificate API resource was created, RFC 3339 format
descriptionstringhuman-readable description of this SSH User Certificate. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this SSH User 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 user certificate
principalsList<string>the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizing the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_optionsMap<string, string>A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensionsMap<string, string>A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
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