Manage keys by using the Web Services API

10min
The  Application Programming Interface (API) enables you to interact with  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  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  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  REST API:
﻿https://docs.futurex.com/cryptohub within the REST API section.
﻿https://CryptoHubURL/keys/v1/docs/ for Swagger interactive API documentation
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 after deployed/ 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  (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
﻿ 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
1
Log in to the  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
1
Log in to the  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 using the API key downloaded in the previous section.
1
Configure the following Postman Workspace - Authorization Parameters:
Auth Type: API Key
Key: X-API-Key
Value: API Key
Add to: 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"
}
{
"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"
}
{
"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"
}
{
"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/
Updated 01 Dec 2024
Did this page help you?
Deploying Key Lifecycle Management Services
Zoho