Create an API Key

Before you can use the API and API Co-Signer, you need to create an API Key. This tutorial will explain how to create an API Key and what to look for throughout the process.

In this tutorial, you will learn how to:

1. Create an API key
2. Obtain the corresponding public key to the API key

Create an API Key

Log into the Safeheron Web Console as a member with Manage API permission and then navigate to Settings -> API to create an API key.

Name Your API Key

The name is a readable identifier for the API Key that allows you to distinguish between them if you have multiple API Keys.

Upload Your Public Key

To ensure data transmission security, Safeheron encrypts API interface request and response data with an asymmetric RSA-4096 encryption algorithm. You must generate a pair of RSA Public and Private keys and upload the public key for the API Key. Safeheron encrypts the API response data using the public key you uploaded.

caution

Please generate your RSA private key in a safe environment and keep it secure, as its compromise could result in the loss of assets.

tip

The uploaded Public Key cannot be altered in any way. If it needs to be replaced, you can generate a new API Key.

Generate the RSA Public and Private keys using the OpenSSL tool as shown below:

• Generate Your Private Key: The file api_private.pem contains the Private Key after executing the following command:

  
  $ openssl genpkey -out api_private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096
  

• Generate Your Public Key: The file api_public.pem contains the Public Key after executing the following command in the same directory

  
  $ openssl rsa -in api_private.pem -out api_public.pem -pubout
  

IP Whitelisting

You must first configure the public IP (IPv4 and IPv6) for the API request using the API Key in the whitelist before requesting the API. If the IP address that initiated the API request is not on the whitelist, the request will be rejected and return an error code of 1011.

caution

If you want to deploy the API Co-Signer, you also need to configure the public IP of the host where the API Co-Signer is located in the whitelist, otherwise the API Co-Signer will not communicate with Safeheron.

tip

If your public IP address changes or you need to use a new public IP address, please update your IP whitelist. Changes to the IP whitelist must be approved by team members via the Safeheron Mobile App prior to taking effect. You can check the status on the Settings -> API page to see if the changes have taken effect.

Set Permissions

The API Key has the following permissions, and you can select the corresponding permissions according to your business needs:

Permission	Description
Read	A default and mandatory permission that calls all readers. For example, accessing wallet accounts, checking transaction history, and so on
Create Transactions (from wallet accounts created from the API)	An API Key with this permission can only initiate transactions using a wallet account created through the API
Create transactions (from a wallet account created within the platform)	API Keys with this permission can and will only initiate transactions through the Safeheron Mobile App's wallet account
Manage Wallet Accounts	With this permission, you can call the wallet-related management interface. For example: creating a wallet account, adding tokens, modifying the status of the wallet account in the Safeheron mobile app, and so on
Approve Transactions	You must configure this permission as well as the default read permissions when creating an API Key for deploying an API Co-Signer to complete an automated approval scenario. Other permissions are not required.

caution

For security purposes, it is recommended that you apply the principle of minimum permissions, i.e configure the API Key with only the permissions necessary for the business scenario.

tip

Changes to API Key permissions are only effective once approved by your team members through the Safeheron App. You can check the status on the Settings -> API page to confirm whether the changes have taken effect.

Obtain the API Key's Public Key

After you create an API Key, Safeheron automatically generates a pair of RSA public-private key pairs. You can get the platform's Public Key from the API key list. At this point, you have obtained:

• API Key
• Platform RSA Public Key
• Locally generated RSA Private Key

The above data is needed when using the API.

For Your Reference

After the API key is created and approved, you can try to create your first wallet using the API.