POST SSH/AddUserPrivateKey

Installs a new user private key on a device. You can only add the private key when the keyset is generated inside Trust Protection Platform or on rotated keysets. The key algorithm and length are taken from the SSH policy of the device folder. If the Algorithm is empty, the default is RSA. If the Key Size is empty, the Length is 2048.

SSH/AddUserPrivateKey API returns immediately after the key generates and inserts into the Trust Protection Platform database. This API call does not wait until the key is actually provisioned on the device (which can take time depending on the configured Agent schedule). To track the progress of key operations, call POST SSH/KeyDetails.

Requirements

  • Permissions

    Administrators must have the following permissions to create a keyset in a policy folder:

    • Device: View permission and Create permission.

    • Keyset policy: View, Read, Write and Private Key Read permission.

    The caller must have one or more of the following ownerships or permissions:

    • Owner permission of any private key in this keyset.
    • Read permission to the device for any key in this keyset.
    • Read permission to the private key for the policy where the self-service key is present.
  • Token scope:  SSH:Manage
  • Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description

DeviceGuid

The GUID that identifies a device. Depending on your environment, the GUID may be expressed with or without curly braces {}. For example, {3d6b61d-1c71-4603-883f-25b8c2ceecdd}. To get the GUID, use POST SSH/KeysetDetails or the UI. For example:

Location of device GUID in UI

Filepath

The installation path of the key on the device.

Format

(Optional) Omit this parameter if the private key should use the policy setting. The key format: OpenSSH, SSH2, PuTTY.

KeysetId

(Optional) If not specified, new keyset will be created.

The identifier of a set of public and private key pairs. Depending on your environment, the value may be expressed with or without curly braces {}. You can get the KeysetId, from POST SSH/KeyUsage or the SSH Keyset Inventory. For example:

Location of KeysetID in the UI

Passphrase

(Optional) Passphrase to encrypt and decrypt the key. Use your company password standards or the National Institute of Standards and Technology (NIST).

PolicyDN

(Optional) The Distinguished Name (DN) of the Policy folder where the new SSH keyset will be created. Omit this parameter the SSH keyset does not go in a Policy folder. By default, SSH keysets are not created in policies. For more information, see About moving SSH keys to a different folder.

Username

Name of user specified device that will own the key.

Returns

Response description

Name

Description

KeyId

The identifier of newly created key.

Keysetid

The identifier for a set of public and private keys. The value is hexadecimal. If there is no private key password, the format is EncryptedPrivateKey-[unique number]. For example, EncryptedPrivateKey-3.

Response

The SSH SshWebResponse object with the operation result. If the keyset generated outside of Trust Protection Platform, error code 6 occurs. For more information, see SSH web error codes.

Example: Assign a keyset to a Policy folder and Device object

Request

POST https://tpp.venafi.example/vedsdk/AddUserPrivateKey 
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "DeviceGuid":"{9063f994-bcf6-4053-b521-94a917123845}",
   "Filepath":"/home/user/.ssh/user.key",
   "Format":"OpenSSH",
   "KeysetId":"2383F0EA3C04430C829E1FFD138C8283A1786C41",
   "PolicyDN":"//VED//Policy//Keyset",
   "Passphrase":"PrivateKeyPassPhrase",
   "Username":"User"
}

Response

HTTP/1.1 200 OK
{
   "KeyId":3,
   "KeysetId":"F6264A646B9B782DCCC254CCCF0917224DE2B605",
   "Response":{
      "Success":true
   }
}