Skip to main content
The CryptoHub Application Programming Interface (API) enables you to interact with CryptoHub by using scripts, programs (such as Postman), or cURL commands from the command line rather than interacting with the web dashboard. Thus, you can schedule routine tasks and procedures and set up automatic responses as needed. The CryptoHub API connects various software systems, applications, and devices, enabling them to communicate with one another, enhancing user experiences, and increasing business efficiency. Consider the following advantages of using the API:
  • Automation: Use them to automate repetitive or time-consuming tasks so you can focus on more complex tasks.
  • Security: Take advantage of an additional layer of protection against unauthorized breaches by requiring authentication and authorization for any request to access sensitive data.
  • Cost efficiency: Access useful third-party tools and infrastructure, which helps avoid the expense of building complex in-house systems.
The CryptoHub API consists of endpoints that support authentication, administration, application logs, custom services management, dashboard, IAM, remote desktop, Google CSE, Google EKM, and Key Management. Key management includes managing keys, key types, approvers, services, and mailer templates with support for key printing. For more information, see the following documentation on the CryptoHub REST API: CryptoHub REST API within the REST API section.

​
Service identification

Use the deployed service UUID to manage keys. To find the Service UUID, go to any deployed service and copy the last section of the webpage URL (such as the numbers afterdeployed/ in this URL: https://CryptoHubURL/cuserv/#/deployed/0140d4ed-d808-0004-0000-541623a0088b).

​
Key identification

Managing keys involves the following associated UUIDs:
  • Key Order UUID: A key generated within CryptoHub (either within the UI or by API) is known as a Key Order. All key-based API operations use the Key Order UUID as the top-level UUID. Find more information on the Key Order at https://CryptoHubURL/keys/v1/docs/ under “rkproto_keys_Key”: objInfo.uuid.
  • Key Version UUID: This UUID is for the versioning of the key and is the legacy UUID used for key identification within the Web UI. This shows up in both the Key Orders Table under the Key Lifecycle Management service and the legacy Key Database within the Administrative Services.

​
Create an application partition and identity

CryptoHub supports both administration and key management access by using the JSON API. You must create an application partition and its associated identity to enable authentication and communication through a JSON web request. The application partition specifies which administrative key management permissions and key access to grant to the application identity.

​
Create an application partition

Perform the following steps to create an application partition:
1
Log in to the CryptoHub web dashboard under dual control with your Administrator users.
2
Select the gear icon in the upper-right corner of the page and go to Administration > User Management > Partitions.
3
Select [ Add ] and configure the following settings:
  • Basic Info
    • Role Name: Enter KeyManagerAPI.
    • Login Count Requirement: Select Normal.
    • HSM Partition: Select Enabled.
    • Role Type: Select Principal.
  • Service Permissions: Select 3DES KTK XOR 3 Components, Generate Key, Import Key.
  • Permissions (none)
  • Advanced Info
    • External Name (none)
    • REST API Login: Select Enabled.
    • Excrypt API Login: Select Disabled.
    • KMIP API Login: Select Disabled.
4
Select [ Deploy ].

​
Create application identity

Perform the following steps to create an application identity:
1
Log in to the CryptoHub web dashboard under dual control with your Administrator users.
2
Select the gear icon in the upper-right corner of the page and go to Administration > User Management > Applications.
3
Select [ Add ] and configure the following settings:
  • Basic Info
    • Login Name: Enter KeyManagerAPI.
    • Common Name: Enter KeyManagerAPI.
    • HSM Application: Select Enabled.
    • Locked: Select Disabled.
  • Partitions: Enter KeyManagerAPI.
  • Authentication: Select API Key.
4
Select [ Deploy ].
Your browser prompts you to download a text file api-key-KeyManagerAPI.txt containing the API key, which you can use for Web API authentication.

​
Authenticate to the application partition

You must authenticate the application identity before executing JSON API calls. The following use case shows authentication by using the API key downloaded in the previous section.
1
Configure the following Postman Workspace - Authorization Parameters:
  • Auth Type: Select API Key
  • Key: Select X-API-Key
  • Value: Select API Key
  • Add to: Select Header
2
Swagger /keys/v1/docs/
3
Select [ Authorize ].
4
Enter the API key and select [ Authorize ] again.

​
Run API key life cycle operations

The following operations generate, import, and list keys.

​
Generate key

Postman Workspace - Body Parameters JSON Syntax:
Text
{
"name": "TEST PEK 3",
"keyType": "3DES PEK",
"serviceUuid": "0140d4ed-d808-0004-0000-541623a0088b"
}
Swagger /keys/v1/docs/

​
Import key

Postman Workspace - Body Parameters JSON Syntax:
Text
{
"name": "TEST PEK 4",
"keyType": "3DES PEK",
"serviceUuid": "0140d4ed-d808-0000-0001-46451947cc93",
"importParams": {
"useModifier": false,
"keyTransferKeyUuid": "0140d4ed-67fc-0008-0001-36180772e5d3",
"format": "Tr31",
"keyblock": "B0096P0TN00E00008378AD73BB7B6408CCA6CA7C14D8BDDDAFE9E75957746E9FB23F31798B69C1F5C0A838DCB0B1408C"
}
}
{
"keyUuid": "0140d4ed-67fc-0018-0002-64fa14ff6881",
"message": "Success",
"status": "Success"
}
Swagger /keys/v1/docs/

​
Get a list of keys

Postman Workspace - Body Parameters JSON Syntax:
Text
{
"name": "TEST PEK 4",
"keyType": "3DES PEK",
"serviceUuid": "0140d4ed-d808-0000-0001-36180772e5d3",
"importParams": {
"useModifier": false,
"keyTransferKeyUuid": "0140d4ed-67fc-0008-0001-36180772e5d3",
"format": "Tr31",
"keyblock": "B0096P0TN00E00008378AD73BB7B6408CCA6CA7C14D8BDDDAFE9E75957746E9FB23F31798B69C1F5C0A838DCB0B1408C"
}
}
{
"keyUuid": "0140d4ed-67fc-0018-0002-64fa14ff6881",
"message": "Success",
"status": "Success"
}
Swagger /keys/v1/docs/