PGP Prerequisites

Some endpoints in Nium's API have prerequisites that your integration needs to comply with before you can use them. These prerequisites are in place for compliance and security purposes.

Specifically, the following APIs require a PGP key (a GPG key using RSA encryption) before you can take advantage of them.

Security

Our APIs use the HTTPS protocol and require a PGP key that your integration needs to include in its requests, and you need to share with Nium.

When you share the PGP key with us, Nium approves and adds your IP address to our allowlist to make sure Nium is the only communicating party when these requests get used.

API actionDescription
API request
  1. Your integration provides a public PGP key to Nium.
  2. Nium encrypts your API request using the provided public PGP key.
  3. Decrypt the API request using your private PGP key.
API response
  1. Nium provides you with a public PGP key to encrypt your API response.
  2. Encrypt your API response using the provided public PGP key.
  3. Nium decrypts the API response using our private PGP key.

Generate PGP keys

To generate a public and private PGP key for the above requests, take the following steps. These steps generate the keys using Git Bash on Windows.

See the following table for a complete list of the commands used.

PGP commands
ActionCommand
Generate a PGP keygpg --full-generate-key
List PGP secret keysgpg --list-secret-keys
Export public keygpg --output clientfile-public.key --armor --export [[email protected]](mailto:[email protected])
Export private keygpg --output clientfile-secret.key --armor --export-secret-key [[email protected]](mailto:[email protected])

Step 1: Use the generate PGP key command

Run the gpg---full-generate-key command.

Step 2: Set the key type

Use 1 to set the type of the generated public and private key to RSA.

Step 3: Set the key length

Set the length of the PGP keys. We recommend setting the length of the keys to 2048 bits.

Step 4: Set expiration time

Set how many days the keys will be valid for. Nium recommends using 0 so the keys don't expire.

Step 5: Enter key owner details

Details requested include:

  • Name of the key owner
  • Email address of the key owner
  • Any additional comments for your future reference

Step 6: Set a passphrase

Set a passphrase for the private PGP key.

Step 7: List the key

List the generated keys using the gpg --list-secret-keys command.

Export PGP keys

Once you've generated a pair of PGP keys, take the following steps to export the keys.

Step 1: Export your public PGP key

Run the $gpg --output company-pgp-public-key.key --armor --export [email protected] command to export your public key.

Running the command creates a file in your home directory with the title company-pgp-public-key.key.

Step 2: Export your private PGP key

Run the $gpg --output company-pgp-private-key.key --armor --export-secret-key [email protected] command to begin exporting your private key.

When prompted, enter the passphrase you set to export the private key.

Entering your passphrase creates a file in your home directory with the title company-pgp-private-key.key.

Step 3: Contact Nium to import the PGP key

Reach out to your Nium account manager or Nium support with your PGP keys ready to share.

Our team will configure the keys in our API with your client resource to encrypt and decrypt the relevant requests and responses.