Introduction

IBM® Key Protect for IBM Cloud® helps you provision encrypted keys for apps across IBM Cloud. As you manage the lifecycle of your keys, you can benefit from knowing that your keys are secured by cloud-based FIPS 140-2 Level 3 hardware security modules (HSMs) that protect against the theft of information.

Key Protect provides a REST API that you can use with any programming language to store, retrieve, and generate encryption keys. For details about using Key Protect, see the IBM Cloud docs.

API endpoint

https://<region>.kms.cloud.ibm.com

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more information, see Regions and locations.

The code examples on this tab use the client library that is provided for Go.

go get -u github.com/IBM/keyprotect-go-client

GitHub:

https://github.com/IBM/keyprotect-go-client

The code examples on this tab use the client library that is provided for NodeJS.

npm install @ibm-cloud/ibm-key-protect

GitHub:

https://github.com/IBM/keyprotect-nodejs-client

The code examples on this tab use the client library that is provided for Python.

pip install -U keyprotect

GitHub:

https://github.com/IBM/keyprotect-python-client

The code examples on this tab use the client library that is provided for Java.

git clone https://github.com/IBM/keyprotect-java-client
cd keyprotect-java-client
mvn install

GitHub:

https://github.com/IBM/keyprotect-java-client

Authentication

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Managing access for Key Protect.

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token and instance ID in API requests.

You can build your API request by pairing a service endpoint with your authentication credentials. For example, if you created a Key Protect service instance for the us-south region, use the following endpoint and API headers to browse keys in your service:

curl -X GET \
    https://us-south.kms.cloud.ibm.com/api/v2/keys \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <access_token>" \
    -H "bluemix-instance: <instance_ID>"

Replace <access_token> with your Cloud IAM token, and <instance_ID> with the IBM Cloud instance ID that identifies your Key Protect service instance.

You can retrieve an access token by first creating an API key, and then exchanging your API key for a Cloud IAM token. For more information, see Retrieving an access token programmatically.

To find out more about setting up the Key Protect API, see Accessing the API.

To retrieve your access token:

curl -X POST \
    https://iam.cloud.ibm.com/identity/token \
    -H "accept: application/json" \
    -H "content-type: application/x-www-form-urlencoded" \
    -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>" > token.json

Replace <API_KEY> with your service credentials. Then use the full access_token value, prefixed by the _Bearer_token type, to authenticate your API requests.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --output JSON

Replace <instance_name> with the unique alias that you assigned to your Key Protect service instance. The GUID value in the JSON output represents the instance ID for the service.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides client config initialization method in which you will need to replace <key_protect_url> with the appropriate service endpoint, the <api_key> with the API key associated with your application, and <instance_ID> with the IBM Cloud instance ID that identifies your Key Protect service instance.

The value kp.DefaultTokenURL for TokenURL defaults to the IAM production URL, but you may need to alter the value to be associated with virtual private networks. Use the client config options in the method to create a new Key Protect client. The method handles the authentication procedure with the provided API_KEY.

To authenticate to Key Protect API:

import (
    "context"
    "encoding/json"
    "fmt"

    kp "github.com/IBM/keyprotect-go-client"
)

func getConfigAPIKey() kp.ClientConfig {
    return kp.ClientConfig{
        BaseURL:    <key_protect_url>,
        APIKey:     <api_key>,
        TokenURL:   kp.DefaultTokenURL,
        InstanceID: <instance_ID>,
        Verbose:    kp.VerboseFailOnly,
    }
}

func main() {
    options := getConfigAPIKey()
    api, err := kp.New(options, kp.DefaultTransport())
    if err != nil {
        fmt.Println("Error creating kp client")
        return
    }
}

To access the API through your service endpoint, you will need to use the following format.

API endpoint format:

https://<region>.kms.cloud.ibm.com

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more informaton, see Regions and locations.

To retrieve your instance ID, run the following command using the CLI:

ibmcloud resource service-instance <instance_name> --output JSON

Replace <instance_name> with the unique alias that you assigned to your Key Protect service instance. The GUID value in the JSON output represents the <instance_ID> for the service.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to export environment variables to match the IBMCLOUD_API_KEY term with the API key associated with your service credentials, another term, IAM_AUTH_URL with the appropriate URL like 'https://iam.cloud.ibm.com/identity/token', another term, KP_SERVICE_URL with the endpoint, including the region, such as https://us-south.kms.cloud.ibm.com, and KP_INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --output JSON

To authenticate to Key Protect API:

const KeyProtectV2 = require('@ibm-cloud/ibm-key-protect/ibm-key-protect-api/v2');
const { IamAuthenticator } = require('@ibm-cloud/ibm-key-protect/auth');

// using external configuration of environment variables
const envConfigs = {
    apiKey: process.env.IBMCLOUD_API_KEY,
    iamAuthUrl: process.env.IAM_AUTH_URL,
    serviceUrl: process.env.KP_SERVICE_URL,
    bluemixInstance: process.env.KP_INSTANCE_ID,
};

// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
    apikey: envConfigs.apiKey,
    url: envConfigs.iamAuthUrl,
});

// Construct the service client.
const keyProtectClient = new KeyProtectV2({
    authenticator,
    serviceUrl: envConfigs.serviceUrl,
});

For more information on the regional endpoint where your data can be accessed, see Regions and locations.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to replace the IBMCLOUD_API_KEY with the API key associated with your application, and KP_INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to replace the IBMCLOUD_API_KEY with the API key associated with your application, and KP_INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

To authenticate to Key Protect API:

import os

import keyprotect
from keyprotect import bxauth

tm = bxauth.TokenManager(api_key=os.getenv("<IBMCLOUD_API_KEY>"))

kp = keyprotect.Client(
    credentials=tm,
    region="<region>",
    service_instance_id=os.getenv("<KP_INSTANCE_ID>")
)

Replace <IBMCLOUD_API_KEY> with your service credentials.

Replace <KP_INSTANCE_ID> with the UUID that identifies your Key Protect instance.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --output JSON

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more information, see Regions and locations.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to replace the IAM_API_KEY with the API key associated with your application, IAM_AUTH_URL with your Cloud IAM token,KEY_PROTECT_URL with a service endpoint, and INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

To authenticate to Key Protect API:

import com.ibm.cloud.ibm_key_protect_api.v2.IbmKeyProtectApi;
import com.ibm.cloud.ibm_key_protect_api.v2.model.*;
import com.ibm.cloud.sdk.core.http.Response;
import com.ibm.cloud.sdk.core.security.*;

public class KPClient {
    
    private static IbmKeyProtectApi testClient;

    public static void main(String[] args) {
        
        IamAuthenticator authenticator = new IamAuthenticator("<IAM_API_KEY>");
        authenticator.setURL("<IAM_AUTH_URL>");
        authenticator.validate();
        
        testClient = new IbmKeyProtectApi("<INSTANCE_ID>", authenticator);
        testClient.setServiceUrl("<KEY_PROTECT_URL>");
    }
}

Replace <INSTANCE_ID> with the UUID that identifies your Key Protect instance.

Replace <IAM_API_KEY> with your service credentials.

Replace <IAM_AUTH_URL> with https://iam.cloud.ibm.com/identity/token.

Replace <KEY_PROTECT_URL> with the service endpoint for your instance that handles your requests.

To retrieve your instance ID, replace <instance_name> in the command as shown:

ibmcloud resource service-instance <instance_name> --output JSON

Your endpoint is specific to the geographic area where your Key Protect service instance resides. For more information, see Regions and locations.

Auditing

You can monitor API activity within your account. Whenever an API method is called, an event is generated that you can then track and audit. The specific event type is listed for each method that generates auditing events. For methods that don't list any events, no events are generated.

For more information about how to track Key Protect activity, see Auditing the events for Key Protect.

Error handling

The Key Protect service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

| Status code | Description | | --- | --- | | 200 OK | Everything worked as expected. | | 201 OK | Everything worked as expected; no content. | | 400 Bad Request | The request was unsuccessful; ensure no required parameters are missing. | | 401 Unauthorized | The parameters were valid but the request failed due insufficient permissions. | | 404 Not Found | The requested resource doesn't exist. | | 410 Gone | The requested resource was deleted and no longer exists. | | 429 Too Many Requests | Too many requests hit the API too quickly. | | 500 Server Error | Something went wrong on Key Protect's end. |

Metadata

When you create or store keys in Key Protect, you can attach key-value data to your resources for easy identification of your keys.

The name, description, and tag parameters are useful for storing information on your resources. For example, you can store corresponding unique identifiers from your app or system on a Key Protect key.

To protect your privacy, do not store any personally identifiable information, such as your name or location, as metadata for your keys.

Pagination

Some API requests might return a large number of results. By specifying the limit and offset parameters at query time, you can retrieve a subset of your keys, starting with the offset value that you specify. For more information, see Retrieving a subset of keys.

There are optional operations that can effect pagination and the resulting list of keys returned by the service. Some operations may still be in development, and will be listed as "Beta" while that is the case.

Search

When used, this operation performs a search, possibly limiting the number of keys returned. If you want to narrow the number of results returned by a search, try using one or a combination of the following values as a prefix for the term you wish to have searched:

not: when specified, inverts the logic the search uses (for example, not:foo will search for keys that have aliases or names that do not contain foo).
escape: everything after this option is take as plaintext (example: escape:not: will search for keys that have an alias or name containing the substring not:).
exact: only looks for exact matches.
alias: only looks for key aliases.
name: only looks for key names.

The list of keys returned is sorted on id by default, if this parameter is not provided.

Sort

When used, this operation sorts the list of keys returned based on one or more key properties. The key properties that can be sorted at this time are:

id
state
extractable
imported
creationDate
lastUpdateDate
lastRotateDate
deletionDate
expirationDate

The list of keys returned is sorted on id by default, if this parameter is not provided.

Rate Limiting

Rate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

An HTTP status code of 429 indicates that the rate limit has been exceeded.

Change log

Important changes, such as additions, updates, and breaking changes, are marked with a change notice in this reference.

New features will be initially released as "beta" implementations.

"Beta" means that the specification is subject to change, with limited support in different environments (from partial support to none at all, depending on the specifics), in order to test new features that are not yet stable for use in production environments.

As part of continued migration and improvement, the algorithmBitSize, algorithmMode, algorithmType and algorithmMetadata fields are deprecated within the Key Protect API.

Key Protect announces several changes to both the structure and to particular names of certain events to better conform with IBM naming conventions.

The alias parameter in the event generated with a key alias added to a key at creation time is being moved from the response data section to the request data section.

Also, to better conform with IBM standards, the names of certain events are changing.

| Old event name | New event name | | --- | --- | | kms.secrets.eventack | kms.secrets-event.ack| | kms.secrets.readmetadata | kms.secrets-metadata.read| | kms.secrets.listkeyversions | kms.secrets-key-versions.list| | kms.secrets.defaultalias | kms.secrets-alias.default| | kms.secrets.createalias | kms.secrets-alias.create| | kms.secrets.deletealias | kms.secrets-alias.delete| | kms.importtoken.create | kms.import-token.create| | kms.importtoken.default | kms.import-token.default| | kms.importtoken.read | kms.import-token.read| | kms.instancepolicies.write | kms.instance-policies.write| | kms.instancepolicies.default | kms.instance-policies.default| | kms.instancepolicies.read | kms.instance-policies.read| | kms.instance.readallowedipport | kms.instance-allowed-ip-port.read| | kms.instance.readipwhitelistport | kms.instance-ip-whitelist-port.read| | kms.keyrings.create | kms.key-rings.create| | kms.keyrings.delete | kms.key-rings.delete| | kms.keyrings.list | kms.key-rings.list| | kms.keyrings.default | kms.key-rings.default| | kms.governance.configread | kms.governance-config.read |

Key Protect | IBM Cloud API Docs