APIKeyManager Utility

Overview

The APIKeyManager utility is a command line tool that generates and maintains an asymmetric key pair which provides a secure way for automated API calls and scripts, as well as CyberArk clients, to connect and authenticate to the Vault.

The private key is stored locally for use by the script or CyberArk client, while the public key is stored in the Vault. Both keys are associated with a username that was previously created in the Vault and used for API authentication.

This utility enables users to:

  • Create a key pair and store the public key in the Vault (e.g. during a component registration, or manual key rotation)

  • Create a key pair and save the public key locally (e.g. when the key registration will be performed by another person or process)

  • Store a previously created public key in the Vault (e.g. when the key was generated by another person or process)

  • Revoke an existing key pair

Usage

  
apikeymanager <COMMAND> <COMMAND_OPTIONS>

 

The following table lists the utility commands.

Command

Description

add

Creates a new API key file and/or adds it to the Vault. This is for component users who do not yet have an existing key.

update

Creates a new API key file and/or updates the existing key in the Vault with the new key.

revoke

Deletes the client user's public key from the Vault. After running this command, this user will not be able to authenticate to the Vault.

The following table lists the command options.

Command

Description

-f

The path for the output credential file that contains the private key.

-t

The CyberArk client's username associated with the key pair.

-u

The Username of a Vault user with 'Manage Users' permissions in the Vault. This user performs the APIKeyManager operation in the Vault.

-a

An API base address used to logon and/or maintain public keys in the backend. For example, https://www.cyberark.com/passwordvault/api/.

-o

The path to an output file that contains a public key which corresponds to the created private key. When this option is used, do not use the -u and -a options. For more information, see the examples below.

-i

The path to a file that contains a public key that was previously created with the -o option. This option does not create a new key pair, but only calls the Vault to add/update the key with the one in the file.

-e

The encryption type of the newly created keypair.
Possible values: ES256 (default), RS512

-l

Logon target for the user.
Possible values: Vault (default), RabbitMQ

To see the available options for each command, run:

 

apikeymanager <COMMAND> -h

Logging

The APIKeyManager utility sends information and error messages to the console, as well as maintaining a log file that contains all types of messages (debug, warning, info, error). This log file is called apikeymanager.log and is stored in the 'Logs' folder with the utility executable.

When the log file reaches 5MB, a backup version of the current log file is saved and a new log file is created. Only one backup file is saved.

Examples

Relevant option

Mandatory

-f

Yes

-t

Yes

-u

Yes

-a

Yes

-e

No

 

  
apikeymanager add -f "c:\creds\user.cred" -t PasswordManager -u administrator -a "https://mycompany.com/passwordvault/api/"

 

 

If the client user already has an associated key in the backend, use the update command instead of add and leave the other options unchanged.

Relevant option

Mandatory

-f

Yes

-t

Yes

-o

Yes

-e

No

 

  
apikeymanager add --credfile "c:\creds\user.cred" --component-username PasswordManager -o "C:\\Temp\\test.cred.pub" -e RS512

Relevant option

Mandatory

-i

Yes

-t

Yes

-u

Yes

-a

Yes

-e

No

 

  
apikeymanager add -i "c:\creds\user.pub" -t PasswordManager -u administrator -a "https://mycompany.com/passwordvault/api/"

 

 

If the client user already has an associated key in the backend, use the update command instead of add and leave the other options unchanged.

Relevant option

Mandatory

-t

Yes

-u

Yes

-a

Yes

 

  
apikeymanager revoke -t PasswordManager -u administrator -a "https://mycompany.com/passwordvault/api/"

 

 

After running this command, the component user will not be able to authenticate to the Vault.

Relevant option

Mandatory

-a

Yes

-t

Yes

-i

Yes

-l

Yes

 

  
apikeymanager add --admin-username="Administrator" -a "http://localhost/PasswordVault/api" -t "PasswordManager" -i "c:\\temp\\test.cred.pub" -l "RabbitMQ,Vault"