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 '{"ssh_certificate_authority_id":"sshca_2NTVHYaRRACIxk2qvp6Ux4NzSqM","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop","principals":["ec2-user","root"],"valid_until":"2023-06-22T19:59:31Z","description":"temporary access to staging machine"}' \
https://api.ngrok.com/ssh_user_certificates
Parameters
ssh_certificate_authority_id | string | the ssh certificate authority that is used to sign this ssh user certificate |
public_key | string | a public key in OpenSSH Authorized Keys format that this certificate signs |
principals | List<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_options | Map<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. |
extensions | Map<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_after | string | The time when the user certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified. |
valid_until | string | The 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. |
description | string | human-readable description of this SSH User Certificate. optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes. |
Response
Returns a 201 response on success
Example Response
{
"id": "sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"created_at": "2023-03-24T19:59:31Z",
"description": "temporary access to staging machine",
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"key_type": "ecdsa",
"ssh_certificate_authority_id": "sshca_2NTVHYaRRACIxk2qvp6Ux4NzSqM",
"principals": [
"ec2-user",
"root"
],
"critical_options": {},
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"valid_after": "2023-03-24T19:59:31Z",
"valid_until": "2023-06-22T19:59:31Z",
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgHGnelva6yD7blm5CjvySpUJm6e4Ov6DzO1B2uoYMVPsAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMk5UVkhZQjBDcEhXQWdNUHJSQWJFY0xJWGNCAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGQeASMAAAAAZJSoIwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIE9nRfY+3vKJZXzUj6wJUutFoBvioVAbBwU6o7Vti69sAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAg92wsbaWHLKlEJDy+EwWyBn/pM7zHaW6v2XcTBcuH27rDmj1qpLgANQyu6PlKAQPP1bf8opvmyHlZnDHbInMO sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB"
}
Fields
id | string | unique identifier for this SSH User Certificate |
uri | string | URI of the SSH User Certificate API resource |
created_at | string | timestamp when the SSH User Certificate API resource was created, RFC 3339 format |
description | string | human-readable description of this SSH User Certificate. optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes. |
public_key | string | a public key in OpenSSH Authorized Keys format that this certificate signs |
key_type | string | the key type of the public_key, one of rsa, ecdsa or ed25519 |
ssh_certificate_authority_id | string | the ssh certificate authority that is used to sign this ssh user certificate |
principals | List<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_options | Map<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. |
extensions | Map<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_after | string | the time when the ssh host certificate becomes valid, in RFC 3339 format. |
valid_until | string | the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before. |
certificate | string | the 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_2NTVHYB0CpHWAgMPrRAbEcLIXcB
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_2NTVHYB0CpHWAgMPrRAbEcLIXcB
Response
Returns a 200 response on success
Example Response
{
"id": "sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"created_at": "2023-03-24T19:59:31Z",
"description": "temporary access to staging machine for alan",
"metadata": "{\"user_email\": \"alan@example.com\"}",
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"key_type": "ecdsa",
"ssh_certificate_authority_id": "sshca_2NTVHYaRRACIxk2qvp6Ux4NzSqM",
"principals": [
"ec2-user",
"root"
],
"critical_options": {},
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"valid_after": "2023-03-24T19:59:31Z",
"valid_until": "2023-06-22T19:59:31Z",
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgHGnelva6yD7blm5CjvySpUJm6e4Ov6DzO1B2uoYMVPsAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMk5UVkhZQjBDcEhXQWdNUHJSQWJFY0xJWGNCAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGQeASMAAAAAZJSoIwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIE9nRfY+3vKJZXzUj6wJUutFoBvioVAbBwU6o7Vti69sAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAg92wsbaWHLKlEJDy+EwWyBn/pM7zHaW6v2XcTBcuH27rDmj1qpLgANQyu6PlKAQPP1bf8opvmyHlZnDHbInMO sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB"
}
Fields
id | string | unique identifier for this SSH User Certificate |
uri | string | URI of the SSH User Certificate API resource |
created_at | string | timestamp when the SSH User Certificate API resource was created, RFC 3339 format |
description | string | human-readable description of this SSH User Certificate. optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes. |
public_key | string | a public key in OpenSSH Authorized Keys format that this certificate signs |
key_type | string | the key type of the public_key, one of rsa, ecdsa or ed25519 |
ssh_certificate_authority_id | string | the ssh certificate authority that is used to sign this ssh user certificate |
principals | List<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_options | Map<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. |
extensions | Map<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_after | string | the time when the ssh host certificate becomes valid, in RFC 3339 format. |
valid_until | string | the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before. |
certificate | string | the 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
{
"ssh_user_certificates": [
{
"id": "sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"created_at": "2023-03-24T19:59:31Z",
"description": "temporary access to staging machine",
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"key_type": "ecdsa",
"ssh_certificate_authority_id": "sshca_2NTVHYaRRACIxk2qvp6Ux4NzSqM",
"principals": [
"ec2-user",
"root"
],
"critical_options": {},
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"valid_after": "2023-03-24T19:59:31Z",
"valid_until": "2023-06-22T19:59:31Z",
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgHGnelva6yD7blm5CjvySpUJm6e4Ov6DzO1B2uoYMVPsAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMk5UVkhZQjBDcEhXQWdNUHJSQWJFY0xJWGNCAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGQeASMAAAAAZJSoIwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIE9nRfY+3vKJZXzUj6wJUutFoBvioVAbBwU6o7Vti69sAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAg92wsbaWHLKlEJDy+EwWyBn/pM7zHaW6v2XcTBcuH27rDmj1qpLgANQyu6PlKAQPP1bf8opvmyHlZnDHbInMO sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB"
}
],
"uri": "https://api.ngrok.com/ssh_user_certificates",
"next_page_uri": null
}
Fields
ssh_user_certificates | SSHUserCertificate | the list of all ssh user certificates on this account |
uri | string | URI of the ssh user certificates list API resource |
next_page_uri | string | URI of the next page, or null if there is no next page |
SSHUserCertificate fields
id | string | unique identifier for this SSH User Certificate |
uri | string | URI of the SSH User Certificate API resource |
created_at | string | timestamp when the SSH User Certificate API resource was created, RFC 3339 format |
description | string | human-readable description of this SSH User Certificate. optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes. |
public_key | string | a public key in OpenSSH Authorized Keys format that this certificate signs |
key_type | string | the key type of the public_key, one of rsa, ecdsa or ed25519 |
ssh_certificate_authority_id | string | the ssh certificate authority that is used to sign this ssh user certificate |
principals | List<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_options | Map<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. |
extensions | Map<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_after | string | the time when the ssh host certificate becomes valid, in RFC 3339 format. |
valid_until | string | the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before. |
certificate | string | the 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_2NTVHYB0CpHWAgMPrRAbEcLIXcB
Parameters
id | string | |
description | string | human-readable description of this SSH User Certificate. optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes. |
Response
Returns a 200 response on success
Example Response
{
"id": "sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB",
"created_at": "2023-03-24T19:59:31Z",
"description": "temporary access to staging machine for alan",
"metadata": "{\"user_email\": \"alan@example.com\"}",
"public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
"key_type": "ecdsa",
"ssh_certificate_authority_id": "sshca_2NTVHYaRRACIxk2qvp6Ux4NzSqM",
"principals": [
"ec2-user",
"root"
],
"critical_options": {},
"extensions": {
"permit-pty": "",
"permit-user-rc": ""
},
"valid_after": "2023-03-24T19:59:31Z",
"valid_until": "2023-06-22T19:59:31Z",
"certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgHGnelva6yD7blm5CjvySpUJm6e4Ov6DzO1B2uoYMVPsAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMk5UVkhZQjBDcEhXQWdNUHJSQWJFY0xJWGNCAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGQeASMAAAAAZJSoIwAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIE9nRfY+3vKJZXzUj6wJUutFoBvioVAbBwU6o7Vti69sAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEAg92wsbaWHLKlEJDy+EwWyBn/pM7zHaW6v2XcTBcuH27rDmj1qpLgANQyu6PlKAQPP1bf8opvmyHlZnDHbInMO sucrt_2NTVHYB0CpHWAgMPrRAbEcLIXcB"
}
Fields
id | string | unique identifier for this SSH User Certificate |
uri | string | URI of the SSH User Certificate API resource |
created_at | string | timestamp when the SSH User Certificate API resource was created, RFC 3339 format |
description | string | human-readable description of this SSH User Certificate. optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes. |
public_key | string | a public key in OpenSSH Authorized Keys format that this certificate signs |
key_type | string | the key type of the public_key, one of rsa, ecdsa or ed25519 |
ssh_certificate_authority_id | string | the ssh certificate authority that is used to sign this ssh user certificate |
principals | List<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_options | Map<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. |
extensions | Map<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_after | string | the time when the ssh host certificate becomes valid, in RFC 3339 format. |
valid_until | string | the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before. |
certificate | string | the 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 |