Retrieve the API endpoint URL

GET /instances/{id}

Retrieves the URL for the dedicated API endpoint for key management operations on a Hyper Protect Crypto Services instance. The endpoint URL varies depending on which regional service endpoint you are using.

Dallas: `https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/`
Frankfurt: `https://eu-de.broker.hs-crypto.cloud.ibm.com/crypto_v2/`
London: `https://eu-gb.broker.hs-crypto.cloud.ibm.com/crypto_v2/`
Madrid: `https://eu-es.broker.hs-crypto.cloud.ibm.com/crypto_v2/`
São-Paulo: `https://br-sao.broker.hs-crypto.cloud.ibm.com/crypto_v2/`
Tokyo: `https://jp-tok.broker.hs-crypto.cloud.ibm.com/crypto_v2/`
Toronto: `https://ca-tor.broker.hs-crypto.cloud.ibm.com/crypto_v2/`
Washington DC: `https://us-east.broker.hs-crypto.cloud.ibm.com/crypto_v2/`

Depending on whether you are using the public or private endpoint, choose the proper endpoint URL in the kms section that is returned in the following formats. Refer to the right-side example pane for an example:

`"public": "api.<region>.hs-crypto.cloud.ibm.com:<port>"`
`"private": "api.private.<region>.hs-crypto.cloud.ibm.com:<port>"`

Request

Path Parameters

id

Required *

string

The IBM Cloud UUID that uniquely identifies the instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.

Query Parameters

Response

200 - The instance connection info was successfully retrieved.

instance_id

string

The v4 UUID used to uniquely identify the instance in IBM Cloud.

apiConnectionInfo

string

Specifies the URI (url:port) where the API can be used.

401 -

404 - The instance could not be found. Verify that the instance ID specified is valid.

500 -

Create a key

POST /api/v2/keys

Creates a new key with specified key material. Hyper Protect Crypto Services designates the resource as either a root key or a standard key based on the `extractable` value that you specify. A successful `POST /keys` operation adds the key to the service and returns the details of the request in the response entity-body, if the Prefer header is set to `return=representation`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.create

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.create

Request

Request Body

Path Parameters

Query Parameters

Response

201 - The key was successfully created.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

400 - The key is missing a required field.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 - There are three possible causes for HTTP 404 while trying to create

a key, specifying a reason code (resources[0].reasons[0].code) as follows:

KEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note the default key ring name is "default."

INSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist.

IMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist.

409 - The import token that was used to encrypt this key has reached its

`maxAllowedRetrievals` or `expirationDate`, and it is no longer available for operations. To create a new import token, use `POST /import_token`.

In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to `409` conflict exceptions.

KEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached.

KEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance.

KEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Hyper Protect Crypto Services only permits the creation or import of keys in your Hyper Protect Crypto Services instance that follow the key creation and import settings listed on the keyCreateImportAccess policy.

IMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

List keys

GET /api/v2/keys

Retrieves a list of keys that are stored in your service instance.

Note: `GET /keys` will not return the key material in the response body. You can retrieve the key material for a standard key with a subsequent `GET /keys/{id}` request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.list

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.list

Request

Path Parameters

Query Parameters

limit

integer

The number of keys to retrieve. By default, `GET /keys` returns the first 200 keys. To retrieve a different set of keys, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5,000. Usage: If you have 20 keys in your instance, and you want to retrieve only the first 5 keys, use `../keys?limit=5`.

offset

integer

The number of keys to skip. By specifying `offset`, you retrieve a subset of keys that starts with the `offset` value. Use `offset` with `limit` to page through your available resources. Usage: If you have 100 keys in your instance, and you want to retrieve keys 26 through 50, use `../keys?offset=25&limit=25`.

state

array

The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. Usage: If you want to retrieve active and deleted keys, use `../keys?state=1,5`.

extractable

boolean

The type of keys to be retrieved. Filters keys based on the `extractable` property. You can use this query parameter to search for keys whose material can leave the service. If set to `true`, standard keys will be retrieved. If set to `false`, root keys will be retrieved. If omitted, both root and standard keys will be retrieved. Usage: If you want to retrieve standard keys, use `../keys?extractable=true`.

search

string

When provided, performs a search, possibly limiting the number of keys returned. Examples:

- &#x60;foobar&#x60; - find keys where the name or any of its aliases contain &#x60;foobar&#x60;, case insentive (i.e. matches &#x60;xfoobar&#x60;, &#x60;Foobar&#x60;).
- &#x60;7f194e42-4261-452d-82ee-21cd3d9ccaae&#x60; (a valid key id) - find keys where the id the key is &#x60;7f194e42-4261-452d-82ee-21cd3d9ccaae&#x60;, or the name or any of its aliases contain &#x60;7f194e42-4261-452d-82ee-21cd3d9ccaae&#x60;, case insentive.

May prepend with options:

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

May prepend with search scopes:

- &#x60;alias:&#x60; &#x3D; search in key aliases for search query
- &#x60;name:&#x60; &#x3D; search in key names for search query

Examples:

- &#x60;not:exact:foobar&#x60;/&#x60;exact:not:foobar&#x60; - find keys where the name nor any of its aliases are *not* exactly &#x60;foobar&#x60; (i.e. matches &#x60;xfoobar&#x60;, &#x60;bar&#x60;, &#x60;foo&#x60;)
- &#x60;exact:escape:not:foobar&#x60; - find keys where the name or any of its aliases are exactly &#x60;not:foobar&#x60;
- &#x60;not:alias:foobar&#x60;/&#x60;alias:not:foobar&#x60; - find keys where any of its aliases do *not* contain &#x60;foobar&#x60;
- &#x60;name:exact:foobar&#x60;/&#x60;exact:name:foobar&#x60; - find keys where the name is exactly &#x60;foobar&#x60;

Note:

By default, if no scopes are provided, search will be performed in both &#x60;name&#x60; and &#x60;alias&#x60; scopes.

Search is only possible on a intial searchable space of at most 5000 keys. If the initial seachable space is greater than 5000 keys, the API returns HTTP 400 with the property resouces[0].reasons[0].code equals to &#x27;KEY_SEARCH_TOO_BROAD&#x27;. 
Use the following filters to reduce the initial searchable space:

- &#x60;state&#x60; (query parameter)
- &#x60;extractable&#x60; (query parameter)
- &#x60;X-Kms-Key-Ring&#x60; (HTTP header)

If the total intial searchable space exceeds the 5000 keys limit and when providing a fully specified key id or when searching within the &#x60;alias&#x60; scope, a lookup
will  be performed and if a key is found, the key will be returned as the only resource and in the response metadata the property &#x60;incompleteSearch&#x60; will
be &#x60;true&#x60;.

When providing a fully specified key id or when searching within the &#x60;alias&#x60; scope, a key lookup is performed in addition to the search. 
This means search will try to lookup a single key that is uniquely identified by the key id or provided alias, this key will be included in the response
as the first resource, before other matches. 

Search scopes are disjunctive, behaving in an *OR* manner. When using more than one search scope,
a match in at least one of the scopes will result in the key being returned.

sort

string

When provided, sorts the list of keys returned based on one or more key properties. To sort on a property in descending order, prefix the term with "-". To sort on multiple key properties, use a comma to separate each properties. The first property in the comma-separated list will be evaluated before the next. 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.

filter

string

When provided, returns the list of keys that match the queried properties. Each key property to be filtered on is specified as the property name itself, followed by an “=“ symbol, and then the value to filter on, followed by a space if there are more properties to filter only. Note: Anything between `<` and `>` in the examples or descriptions represent placeholder to specify the value Basic format: <propertyA>=<valueB> <propertyB>=<valueB> - The value to filter on may contain a value related to the property itself, or an operator followed by a value accepted by the operator - Only one operator and value, or one value is accepted per property at a time Format with operator/value pair: <propertyA>=<operatorA>:<valueA> Up to three of the same property may be specified at a time. The key properties that can be filtered at this time are:

`creationDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`deletionDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`expirationDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`extractable`
- Boolean true or false without quotes, case-insensitive
`lastRotateDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`lastUpdateDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`state`
- A list of comma-separated integers with no space in between: 0,1,2,3,5
`hasMigrationIntent`
- Boolean true or false without quotes, case-insensitive

Comparison operations (operators) that can be performed on date values are:

`lte:<value>` Less than or equal to - `lt:<value>` Less than - `gte:<value>` Greater than or equal to - `gt:<value>` Greater than A special keyword for date, `none` (case-insensitive), may be used to retreive keys that do not have that property. This is useful for `lastRotateDate`, where only keys that have never been rotated can be retreived. Examples:
`lastRotateDate="2022-02-15T00:00:00Z"` Filter keys that were last rotated on February 15, 2022 - `lastRotateDate=gte:"2022-02-15T00:00:00Z"` Filter keys that were last rotated after or on February 15, 2022 - `lastRotateDate=gte:"2022-02-15T00:00:00Z" lastRotateDate=lt:"2022-03-15T00:00:00Z"` Filter keys that were last rotated after or on February 15, 2022 but before (not including) March 15, 2022 - `lastRotateDate="2022-02-15T00:00:00Z" state=0,1,2,3,5 extractable=false` Filter root keys that were last rotated on February 15, 2022, with any state Note: When you filter by `state` or `extractable` in this query parameter, you will not be able to use the deprecated `state` or `extractable` independent query parameter. You will get a 400 response code if you specify a value for one of the two properties in both this filter query parameter and the deprecated independent query of the same name (the same applies vice versa).

Response

200 - The list of keys was successfully retrieved.

metadata

CollectionMetadataListKeys

The metadata that describes the list keys response

resources

array

A collection of resources.

400 - If reason code (resouces[0].reasons[0].code) is present and is equal to 'KEY_SEARCH_TOO_BROAD', the total searchable space is more than 5000 keys.

Try using a filter to reduce the seachable space.

401 -

429 -

500 -

Retrieve key total

HEAD /api/v2/keys

Returns the same HTTP headers as a GET request without returning the entity-body. This operation returns the number of keys in your instance in a header called `Key-Total`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.head

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.head

Request

Path Parameters

Query Parameters

state

array

extractable

boolean

filter

string

`creationDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`deletionDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`expirationDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`extractable`
- Boolean true or false without quotes, case-insensitive
`lastRotateDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`lastUpdateDate`
- Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”
`state`
- A list of comma-separated integers with no space in between: 0,1,2,3,5
`hasMigrationIntent`
- Boolean true or false without quotes, case-insensitive

Comparison operations (operators) that can be performed on date values are:

`lte:<value>` Less than or equal to - `lt:<value>` Less than - `gte:<value>` Greater than or equal to - `gt:<value>` Greater than A special keyword for date, `none` (case-insensitive), may be used to retreive keys that do not have that property. This is useful for `lastRotateDate`, where only keys that have never been rotated can be retreived. Examples:
`lastRotateDate="2022-02-15T00:00:00Z"` Filter keys that were last rotated on February 15, 2022 - `lastRotateDate=gte:"2022-02-15T00:00:00Z"` Filter keys that were last rotated after or on February 15, 2022 - `lastRotateDate=gte:"2022-02-15T00:00:00Z" lastRotateDate=lt:"2022-03-15T00:00:00Z"` Filter keys that were last rotated after or on February 15, 2022 but before (not including) March 15, 2022 - `lastRotateDate="2022-02-15T00:00:00Z" state=0,1,2,3,5 extractable=false` Filter root keys that were last rotated on February 15, 2022, with any state Note: When you filter by `state` or `extractable` in this query parameter, you will not be able to use the deprecated `state` or `extractable` independent query parameter. You will get a 400 response code if you specify a value for one of the two properties in both this filter query parameter and the deprecated independent query of the same name (the same applies vice versa).

Response

200 - The metadata was successfully retrieved.

401 -

403 -

429 -

500 -

Create a key with policy overrides

POST /api/v2/keys_with_policy_overrides

Creates a new key with specified key material and key policies. This API overrides the policy configurations set at instance level with policies provided in the payload. Hyper Protect Crypto Services designates the resource as a root key or a standard key based on the extractable value that you specify. A successful `POST /keys_with_policy_overrides` operation adds the key and key policies to the service and returns the details of the request in the response entity-body, if the Prefer header is set to `return=representation`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets-with-policy-overrides.create

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets-with-policy-overrides.create

Request

Request Body

Path Parameters

Query Parameters

Response

201 - The key was successfully created.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

400 - The key is either missing a required field or it may contain an invalid or malformed input.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 - There are three possible causes for HTTP 404 while trying to create

a key, specifying a reason code (resources[0].reasons[0].code) as follows:

KEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note the default key ring name is "default." INSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist. IMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist.

409 - The import token that was used to encrypt this key has reached its

`maxAllowedRetrievals` or `expirationDate`, and it is no longer available for operations. To create a new import token, use `POST /import_token`. In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to `409` conflict exceptions. KEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached. KEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance. KEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Hyper Protect Crypto Services only permits the creation or import of keys in your Hyper Protect Crypto Services instance that follow the key creation and import settings listed on the keyCreateImportAccess policy. IMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Retrieve a key

GET /api/v2/keys/{id}

Retrieves a key and its details by specifying the ID or alias of the key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.read

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.read

Request

Path Parameters

id

Required *

string

The v4 UUID or alias that uniquely identifies the key.

Query Parameters

Response

200 - The key was successfully retrieved. If the key was previously deleted, `keyVersion.creationDate` is omitted from the request response.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

400 - The key could not be retrieved due to a malformed, invalid, or missing ID.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 - The key could not be found. Verify that the key ID specified is valid.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

wrap or encrypt a data encryption key

`unwrap`: Use a root key to unwrap or decrypt a data encryption key

`rewrap`: Use a root key to rewrap or reencrypt a data encryption key

`rotate`: Create a new version of a root key

`disable`: Disable operations for a key

`enable`: Enable operations for a key

`setKeyForDeletion`: Authorize deletion for a key with a dual authorization policy

`unsetKeyForDeletion`: Remove an authorization for a key with a dual authorization policy

`restore`: Restore a previously deleted key

Note: If you unwrap a wrapped data encryption key (WDEK) that was not wrapped by the latest version of the key, the service also returns the a new WDEK, wrapped with the latest version of the key as the ciphertext field. The recommendation is to store and use that WDEK, although older WDEKs will continue to work.">

Invoke an action on a key

POST /api/v2/keys/{id}

Note: This API has been deprecated and transitioned to individual request paths. Existing actions using this API will continue to be supported, but new actions will no longer be added to it. We recommend, if possible, aligning your request URLs to the new API path. The generic format of actions is now the following: `/api/v2/keys/<key_ID>/actions/<action>` where `key_ID` is the key you want to operate on/with and `action` is the same action that was passed as a query parameter previously.

Invokes an action on a specified key. This method supports the following actions:

`wrap`: Use a root key to wrap or encrypt a data encryption key
`unwrap`: Use a root key to unwrap or decrypt a data encryption key
`rewrap`: Use a root key to rewrap or reencrypt a data encryption key
`rotate`: Create a new version of a root key
`disable`: Disable operations for a key
`enable`: Enable operations for a key
`setKeyForDeletion`: Authorize deletion for a key with a dual authorization policy
`unsetKeyForDeletion`: Remove an authorization for a key with a dual authorization policy
`restore`: Restore a previously deleted key

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.wrap
hs-crypto.secrets.unwrap
hs-crypto.secrets.rotate
hs-crypto.secrets.rewrap
hs-crypto.secrets.setkeyfordeletion
hs-crypto.secrets.unsetkeyfordeletion
hs-crypto.secrets.disable
hs-crypto.secrets.enable
hs-crypto.secrets.restore

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.wrap
hs-crypto.secrets.unwrap
hs-crypto.secrets.rotate
hs-crypto.secrets.rewrap
hs-crypto.secrets.setkeyfordeletion
hs-crypto.secrets.unsetkeyfordeletion
hs-crypto.secrets.disable
hs-crypto.secrets.enable
hs-crypto.secrets.restore

Request

Request Body

Path Parameters

Query Parameters

action

Required *

string

The action to perform on the specified key.

Response

200 - Successful key operation.

201 - The imported key was successfully restored.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

204 - Successful key operation.

400 - Your authentication data or key is invalid, or the entity-body is missing a required field.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 -

409 - The key is not in an appropriate state, so the KeyAction has failed.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 -

422 - The ciphertext provided for the unwrap operation was not wrapped by this key.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Update (patch) a key

PATCH /api/v2/keys/{id}

Update attributes of a key. Currently only the following attributes are applicable for update: - keyRingID Note: If provided, the `X-Kms-Key-Ring` header should specify the key's current key ring. To change the key ring of the key, specify the new key ring in the request body.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.patch

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.patch

Request

Request Body

The base request for patch key.

Response

200 - Successful key update.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

An array of resources.

400 -

401 -

404 - There are two possible causes for HTTP 404 while trying to update a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_NOT_FOUND_ERR: The key could not be found. KEY_RING_NOT_FOUND_ERR: Key could not be updated, key ring specified does not exist.

410 -

429 -

500 -

enable a dual authorization policy to safely delete keys from your service instance.

Important: After a key has been deleted, any data that is encrypted by the key becomes inaccessible, though this can be reversed if the key is restored within the 30-day time frame. After 30 days, key metadata, registrations, and policies are available for up to 90 days, at which point the key becomes eligible to be purged. Note that once a key is no longer restorable and has been purged, its associated data can no longer be accessed.

Note: By default, Hyper Protect Crypto Services blocks the deletion of a key that's protecting a cloud resource, such as a Cloud Object Storage bucket. Use `GET keys/{id}/registrations` to verify if the key has an active registration to a resource. To delete the key and its associated registrations, set the optional `force` parameter to `true`.">

Delete a key

DELETE /api/v2/keys/{id}

Deletes a key by specifying the ID or alias of the key.

By default, Hyper Protect Crypto Services requires a single authorization to delete keys. For added protection, you can enable a dual authorization policy to safely delete keys from your service instance.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.delete

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.delete

Request

Path Parameters

Query Parameters

force

boolean

If set to `true`, Hyper Protect Crypto Services forces deletion on a key that is protecting a cloud resource, such as a Cloud Object Storage bucket. The action removes any registrations that are associated with the key. Note: If a key is protecting a cloud resource that has a retention policy, Hyper Protect Crypto Services cannot delete the key. Use `GET keys/{id}/registrations` to review registrations between the key and its associated cloud resources. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.

Response

200 - The key was successfully deleted. The status code is the only response, unless the `prefer` parameter contains `return=representation`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

204 - The key was successfully deleted. No content. The status code is the only response, unless the `prefer` parameter contains `return=representation`.

400 - The key cannot be deleted due to a malformed, invalid, or missing ID.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 -

409 - There are three possible causes for HTTP 409 while trying to delete

a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

AUTHORIZATIONS_NOT_MET: The key cannot be deleted because it failed the dual authorization request. Before you delete this key, make sure dual authorization procedures are followed. See the topic, Deleting keys using dual authorization.

PROTECTED_RESOURCE_ERR: The key cannot be deleted because the key has one or more associated resources. See the topic, Considerations before deleting and purging a key.

PREV_KEY_DEL_ERR: The key cannot be deleted because it's protecting a cloud resource that has a retention policy. Before you delete this key, contact an account owner to remove the retention policy on each resource that is associated with the key. See the topic, Considerations before deleting and purging a key.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 -

429 -

500 -

Retrieve key metadata

GET /api/v2/keys/{id}/metadata

Retrieves the details of a key by specifying the ID of the key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.readmetadata

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets-metadata.read

Request

Response

200 - The key metadata was successfully retrieved.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

400 - The key metadata could not be retrieved due to a malformed, invalid, or missing ID or alias.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 - The key metadata for the key with specified ID could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Purge a deleted key

DELETE /api/v2/keys/{id}/purge

Purges all key metadata and registrations associated with the specified key. This method requires setting the KeyPurge permission that is not enabled by default. Purging a key can only be applied to a key in the Destroyed (5) state. After a key is deleted, there is a wait period of up to four hours before purge key operation is allowed. Important: When you purge a key, you permanently shred its contents and associated data. The action cannot be reversed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.purge

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.purge

Request

Path Parameters

Query Parameters

Response

200 - The key was successfully purged.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

204 - The key was successfully purged. No content.

400 - The key cannot be purged due to a malformed ID.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 -

409 - There are two possible causes for HTTP 409 while trying to delete a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

REQ_TOO_EARLY_ERR: The key could not be purged due to wait period of four hours has not been reached. KEY_ACTION_INVALID_STATE_ERR: The key could not be purged because it is not in the Destroyed (5) state.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Restore a key

POST /api/v2/keys/{id}/restore

Restore a key that has been deleted.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.restore

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.restore

Request

Request Body

The base request parameters for restore key action.

Path Parameters

Query Parameters

Response

201 - The key was successfully restored.

400 -

401 -

404 - The key could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - There are three possible causes for HTTP 409 while trying to restore a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the `Destroyed` (5) state. REQ_TOO_EARLY_ERR: Key could not be restored. The key was updated recently, wait and try again. Restoring a key is only allowed when 30 seconds after key is deleted has passed. KEY_RING_RESOURCE_QUOTA_ERR: Key could not be restored. The resource quota for key rings in this instance has been reached and key rings cannot be created.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Learn more.">

List key versions

GET /api/v2/keys/{id}/versions

Retrieves all versions of a root key by specifying the ID or alias of the key.

When you rotate a root key, you generate a new version of the key. If you're using the root key to protect resources across IBM Cloud, the registered cloud services that you associate with the key use the latest key version to wrap your data. Learn more.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.listkeyversions

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets-key-versions.list

Request

Path Parameters

Query Parameters

limit

integer

The number of key versions to retrieve. By default, `GET /versions` returns the first 200 key versions. To retrieve a different set of key versions, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5,000. Usage: If you have a key with 20 versions in your instance, and you want to retrieve only the first 5 versions, use `../versions?limit=5`.

offset

integer

The number of key versions to skip. By specifying `offset`, you retrieve a subset of key versions that starts with the `offset` value. Use `offset` with `limit` to page through your available resources. Usage: If you have a key with 100 versions in your instance, and you want to retrieve versions 26 through 50, use `../versions?offset=25&limit=25`.

totalCount

boolean

If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of key versions that match the request, disregarding limit and offset. The default is set to false. Usage: To return the `totalCount` value for use with pagination, use `../versions?totalCount=true`.

allKeyStates

boolean

If set to `true`, returns the key versions of a key in any state. Usage: If you have deleted a key and still want to retrieve its key versions use `../versions?allKeyStates=true`.

Response

200 - The list of key versions was successfully retrieved.

metadata

ListCollectionMetadata

resources

array

An array of resources.

400 -

401 -

404 -

409 - The key is not in an active state.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 -

Wrap a key

POST /api/v2/keys/{id}/actions/wrap

Use a root key to wrap or encrypt a data encryption key. When present, the ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.wrap

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.wrap

Request

Request Body

The base request for wrap key action.

Response

200 - The key was successfully wrapped.

plaintext

string

The data encryption key (DEK) used in wrap actions when the query parameter is set to `wrap`. The system returns a base64 encoded plaintext in the response entity-body when you perform an `unwrap` action on a key. To wrap an existing DEK, provide a base64 encoded plaintext during a `wrap` action. To generate a new DEK, omit the `plaintext` property. Hyper Protect Crypto Services generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value. Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available for `unwrap` actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.

ciphertext

string

The wrapped data encryption key (WDEK) that you can export to your app or service. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Hyper Protect Crypto Services. The value is base64 encoded.

keyVersion

object

Properties associated with a specific key version.

400 - The request is malformed or illegal.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - The key could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The key is not in the `Active` (1) state.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Unwrap a key

POST /api/v2/keys/{id}/actions/unwrap

Use a root key to unwrap or decrypt a data encryption key.

Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available for `unwrap` actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext and latest key version in the response. Use the latest ciphertext for future unwrap operations.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.unwrap

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.unwrap

Request

Request Body

The base request for unwrap key action.

Response

200 - Successfully unwrapped key.

plaintext

string

ciphertext

string

keyVersion

object

Properties associated with a specific key version.

rewrappedKeyVersion

object

Properties associated with a specific key version.

400 - The request is malformed or illegal.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - The key could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The key is not in the `Active` (1) or `Deactivated` (3) state.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

422 - The ciphertext provided was not wrapped by this key.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Rewrap a key

POST /api/v2/keys/{id}/actions/rewrap

Use a root key to rewrap or reencrypt a data encryption key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.rewrap

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.rewrap

Request

Request Body

The base request for rewrap key action.

Response

200 - The key was successfully rewrapped.

ciphertext

string

keyVersion

object

Properties associated with a specific key version.

rewrappedKeyVersion

object

Properties associated with a specific key version.

400 - The request is malformed or illegal.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - The key could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The key is not in the `Active` (1) or `Deactivated` (3) state.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

422 - The ciphertext provided was not wrapped by this key.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Rotate a key

POST /api/v2/keys/{id}/actions/rotate

Create a new version of a root key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.rotate

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.rotate

Request

Request Body

The base request for rotate key action.

Path Parameters

Query Parameters

Response

204 - The key was successfully rotated. No content.

400 - The request is malformed or illegal.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - There are three possible causes for HTTP 404 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_NOT_FOUND_ERR: The key could not be found. INSTANCE_NOT_FOUND_ERR: Key could not be rotated, specified instance does not exist. IMPORT_TOKEN_NOT_FOUND_ERR: Key could not be rotated, import_token does not exist.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - There are four possible causes for HTTP 409 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the `Active` (1) or `Deactivated` (3) state. KEY_ROTATION_NOT_PERMITTED: Key could not be rotated, this key has been rotated within the last hour, only one rotate action per hour is permitted. KEY_CREATE_IMPORT_ACCESS_ERR: Instance policy does not allow this action. IMPORT_TOKEN_EXPIRED_ERR: Key could not be rotated, the import token has expired.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Set a key for deletion

POST /api/v2/keys/{id}/actions/setKeyForDeletion

Authorize deletion for a key with a dual authorization policy.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.setkeyfordeletion

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.setkeyfordeletion

Request

Response

204 - The key was successfully set for deletion. No content.

400 -

401 -

404 - There are two possible causes for HTTP 404 while trying to set a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_NOT_FOUND_ERR: The key could not be found.

DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The key does not have a dual-authorization delete policy.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Unset a key for deletion

POST /api/v2/keys/{id}/actions/unsetKeyForDeletion

Remove an authorization for a key with a dual authorization policy.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.unsetkeyfordeletion

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.unsetkeyfordeletion

Request

Response

204 - The key was successfully unset for deletion. No content.

400 -

401 -

404 - There are two possible causes for HTTP 404 while trying to unset a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_NOT_FOUND_ERR: The key could not be found. DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The key does not have a dual-authorization delete policy.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Enable a key

POST /api/v2/keys/{id}/actions/enable

Enable operations for a key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.enable

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.enable

Request

Response

204 - The key was successfully enabled. No content.

400 - The request is malformed or illegal.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - The key could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - There are two possible causes for HTTP 409 while trying to enable a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the `Suspended` (2) state or the state of the key has changed within the last 30 seconds. REQ_TOO_EARLY_ERR: Key could not be enabled, as the key was updated recently. After key is disabled, the event must fully propagate before enabling key operations. Wait and try again.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Disable a key

POST /api/v2/keys/{id}/actions/disable

Disable operations for a key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.disable

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.disable

Request

Response

204 - The key was successfully disabled. No content.

400 - The request is malformed or illegal.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - The key could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The requested key is not in the `Active` (1) state.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

410 - The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Sync associated resources

POST /api/v2/keys/{id}/actions/sync

Initiate a manual data synchronization request to the associated resources of a key. Regular key lifecycle events automatically notify integrated services of any change. However, in the case a service does not respond to a key lifecycle event notification after four hours, the `sync` API may be used to initiate a renotification to the integrated services that manage the associated resources linked to the key.

Note: The services that manage the associated resources linked to the key are responsible for maintaining current records of the key state and version. Hyper Protect Crypto Services does not have the ability to force data synchronization for other services, which may take up to four hours to complete. The `sync` API is meant to initiate a request for all associated resources to synchronize their key records with the information returned from the Hyper Protect Crypto Services KMS API.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.sync

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets.sync

Request

Response

204 - The sync of associate resources for a key has been initiated. No content.

400 - The request is malformed or illegal.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - There are two possible causes for HTTP 404 for the synchronization request, the reason code (resources[0].reasons[0].code) as follows:

KEY_NOT_FOUND: The specified key could not be found. NOT_SUPPORTED_IN_SATELLITE_LOCATION: The synchronization request for the specified key is not supported in this location.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The key has been synced or updated (i.e. rotated, restored, disabled, enabled, deleted) within the last hour.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

automatic rotation policy or a dual authorization policy to protect against the accidental deletion of keys. Use `PUT /keys/{id}/policies` to create new policies for a key or update an existing policy.">

Set key policies

PUT /api/v2/keys/{id}/policies

Creates or updates one or more policies for the specified key.

You can set policies for a key, such as an automatic rotation policy or a dual authorization policy to protect against the accidental deletion of keys. Use `PUT /keys/{id}/policies` to create new policies for a key or update an existing policy.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.policies.write

Auditing

Calling this method generates the following auditing event.

hs-crypto.policies.write

Request

Request Body

Path Parameters

Query Parameters

policy

string

The type of policy that is associated with the specified key.

Response

200 - The policy or policies were successfully created or updated.

204 - The policy or policies were successfully created or updated. No content.

400 - The policy or policies cannot be created or updated due to a malformed, invalid, or missing ID.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

410 -

422 - The key with specified ID is invalid for use with policies.

A key must be a root key (non-extractable) in the Activated (1) state.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

automatic rotation policy or a dual authorization policy to protect against the accidental deletion of keys. Use `GET /keys/{id}/policies` to browse the policies that exist for a specified key.">

List key policies

GET /api/v2/keys/{id}/policies

Retrieves a list of policies that are associated with a specified key.

You can set policies for a key, such as an automatic rotation policy or a dual authorization policy to protect against the accidental deletion of keys. Use `GET /keys/{id}/policies` to browse the policies that exist for a specified key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.policies.read

Auditing

Calling this method generates the following auditing event.

hs-crypto.policies.read

Request

Path Parameters

Query Parameters

policy

string

The type of policy that is associated with the specified key.

Response

200 - The policy resources were successfully retrieved.

400 - The request is missing a required field or contains invalid values.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 -

429 -

500 -

Set instance policies

PUT /api/v2/instance/policies

Creates or updates one or more policies for the specified service instance.

Note: When you set an instance policy, Hyper Protect Crypto Services associates the policy information with keys that you add to the instance after the policy is updated. This operation does not affect existing keys in the instance.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.instancepolicies.write

Auditing

Calling this method generates the following auditing event.

hs-crypto.instance-policies.write

Request

Request Body

Path Parameters

Query Parameters

policy

string

The type of policy that is associated with the specified instance.

Response

204 - The policy or policies were successfully created or updated. No content.

400 - The policy or policies cannot be created or updated due to a malformed or invalid request.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 - There are two possible causes for HTTP 403 while trying to set instance policies, specifying a reason code (resouces[0].reasons[0].code) as follows:

FEATURE_RESTRICTED_ERR: Your service is not authorized to make this request. Ensure that an authorization exists between your service and Hyper Protect Crypto Services. CONFIG_RULE_CONFLICT_ERR: Instance policy could not be created, requested change is not compliant with configuration rules.

410 -

429 -

500 -

List instance policies

GET /api/v2/instance/policies

Retrieves a list of policies that are associated with a specified service instance.

You can manage advanced preferences for keys in your service instance by creating instance-level policies. Use `GET /instance/policies` to browse the policies that are associated with the specified instance. Currently, dual authorization policies are supported.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.instancepolicies.read

Auditing

Calling this method generates the following auditing event.

hs-crypto.instance-policies.read

Request

Path Parameters

Query Parameters

policy

string

The type of policy that is associated with the specified instance.

Response

200 - The policy resources were successfully retrieved.

400 - The request is missing a required field or contains invalid values.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 -

429 -

500 -

Create an import token

POST /api/v2/import_token

Creates an import token that you can use to encrypt and import root keys into the service. Learn more.

When you call `POST /import_token`, Hyper Protect Crypto Services creates an RSA key-pair from its HSMs. The service encrypts and stores the private key in the HSM, and returns the corresponding public key when you call `GET /import_token`. You can create only one import token per service instance.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.importtoken.create

Auditing

Calling this method generates the following auditing event.

hs-crypto.import-token.create

Request

Request Body

ImportToken

The base request to create an import token.

expiration

number

The time in seconds from the creation of an import token that determines how long its associated public key remains valid. The minimum value is `300` seconds (5 minutes), and the maximum value is `86400` (24 hours). The default value is `600` (10 minutes).

maxAllowedRetrievals

number

The number of times that an import token can be retrieved within its expiration time before it is no longer accessible.

creationDate

string

The date the import token was created. The date format follows RFC 3339.

expirationDate

string

The date the import token expires. The date format follows RFC 3339.

remainingRetrievals

number

The number of retrievals that are available for the import token before it is no longer accessible.

Response

200 - The import token was successfully created.

expiration

number

maxAllowedRetrievals

number

The number of times that an import token can be retrieved within its expiration time before it is no longer accessible.

creationDate

string

The date the import token was created. The date format follows RFC 3339.

expirationDate

string

The date the import token expires. The date format follows RFC 3339.

remainingRetrievals

number

The number of retrievals that are available for the import token before it is no longer accessible.

400 - The import token cannot be created due to a malformed or invalid request.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

429 -

500 -

Retrieve an import token

GET /api/v2/import_token

Retrieves the import token that is associated with your service instance.

When you call `GET /import_token`, Hyper Protect Crypto Services returns the public key that you can use to encrypt and import key material to the service, along with details about the key.

Note: After you reach the `maxAllowedRetrievals` or `expirationDate` for the import token, the import token and its associated public key can no longer be used for key operations. To create a new import token, use `POST /import_token`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.importtoken.read

Auditing

Calling this method generates the following auditing event.

hs-crypto.import-token.read

Request

Response

200 - The import token was successfully retrieved.

expiration

number

maxAllowedRetrievals

number

The number of times that an import token can be retrieved within its expiration time before it is no longer accessible.

creationDate

string

The date the import token was created. The date format follows RFC 3339.

expirationDate

string

The date the import token expires. The date format follows RFC 3339.

remainingRetrievals

number

The number of retrievals that are available for the import token before it is no longer accessible.

payload

string

The public encryption key that you can use to encrypt key material before you import it into the service. This value is a PEM-encoded public key in PKIX format. Because PEM encoding is a binary format, the value is base64 encoded.

nonce

string

The nonce value that is used to verify a key import request. Encrypt and provide the encrypted nonce value when you use `POST /keys` to securely import a key to the service.

401 -

403 -

404 - There are two possible causes for HTTP 404 while trying to retrieve an import token, specifying a reason code (resouces[0].reasons[0].code) as follows:

IMPORT_TOKEN_NOT_FOUND_ERR: An import token was not found in the specified service instance. To create an import token, use `POST /import_token`. INSTANCE_NOT_FOUND_ERR: Import token could not be retrieved, instance does not exist.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - The import token has reached its `maxAllowedRetrievals` or

`expirationDate`, and it is no longer available for use. To create a new import token, use `POST /import_token`.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

List registrations for a key

GET /api/v2/keys/{id}/registrations

Retrieves a list of registrations that are associated with a specified root key.

When you use a root key to protect an IBM Cloud resource, such as a Cloud Object Storage bucket, Hyper Protect Crypto Services creates a registration between the resource and root key. You can use `GET /keys/{id}/registrations` to understand which cloud resources are protected by the key that you specify.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.registrations.list

Auditing

Calling this method generates the following auditing event.

hs-crypto.registrations.list

Request

Path Parameters

Query Parameters

limit

integer

The number of registrations to retrieve. By default returns the first 200 registrations. To retrieve a different set of registrations, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5,000. Usage: If you have 20 registrations that are associated with a key, and you want to retrieve only the first 5 registrations, use `../registrations?limit=5`.

offset

integer

The number of registrations to skip. By specifying `offset`, you retrieve a subset of registrations that starts with the `offset` value. Use `offset` with `limit` to page through your available resources. Usage: If you have 100 registrations that are associated with a key, and you want to retrieve registrations 26 through 50, use `../registrations?offset=25&limit=25`.

urlEncodedResourceCRNQuery

string

Filters for resources that are associated with a specified Cloud Resource Name (CRN) by using URL encoded wildcard characters (``). The parameter should contain all CRN segments and must be URL encoded. Supports a prefix search when you specify `` on the last CRN segment. Usage: To list registrations that are associated with all resources in `<service-instance>`, use a URL encoded version of the following string: `crn:v1:bluemix:public:<service-name>:<location>:a/<account>:<service-instance>::`. To search for subresources, use the following CRN format: `crn:v1:bluemix:public:<service-name>:<location>:a/<account>:<service-instance>:<resource-type>:<resource>/<subresource>`. For more examples, see CRN query examples.

preventKeyDeletion

boolean

Filters registrations based on the `preventKeyDeletion` property. You can use this query parameter to search for registered cloud resources that are non-erasable due to a retention policy. This policy should only be set if a WORM policy ( https://www.ibm.com/docs/en/spectrum-scale/5.0.1?topic=ics-how-write-once-read-many-worm-storage-works) must be satisfied. Do not set this policy by default. Usage: To search for registered cloud resources that have a retention policy, use `../registrations?preventKeyDeletion=true`.

totalCount

boolean

If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of registrations that match the request, disregarding limit and offset. Usage: To return the `totalCount` value for use with pagination, use `../registrations?totalCount=true`.

Response

200 - The list of registrations was successfully retrieved.

metadata

CollectionMetadataWithTotalCount

The metadata that describes the resource array.

resources

array

A collection of resources.

400 - The list of registrations could not be retrieved due to a malformed `urlEncodedResourceCRN`, an invalid or missing request body, or an invalid key ID.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

404 - The key with specified ID could not be found.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

List registrations for any key

GET /api/v2/keys/registrations

Retrieves a list of registrations that match the Cloud Resource Name (CRN) query that you specify.

When you use a root key to protect an IBM Cloud resource, such as a Cloud Object Storage bucket, Hyper Protect Crypto Services creates a registration between the resource and root key. You can use `GET /keys/registrations` to understand which cloud resources are protected by keys in your Key Protect service instance.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.registrations.list

Auditing

Calling this method generates the following auditing event.

hs-crypto.registrations.list

Request

Path Parameters

Query Parameters

urlEncodedResourceCRNQuery

string

Filters for resources that are associated with a specified Cloud Resource Name (CRN) by using URL encoded wildcard characters (``). The parameter should contain all CRN segments and must be URL encoded. If provided, the parameter should not contain (``) in the first eight segments. If this parameter is not provided, registrations for all keys in the requested service instance are returned.

limit

integer

offset

integer

preventKeyDeletion

boolean

Filters registrations based on the `preventKeyDeletion` property. You can use this query parameter to search for registered cloud resources that are non-erasable due to a retention policy. This policy should only be set if a WORM policy (https://www.ibm.com/docs/en/spectrum-scale/5.0.1?topic=ics-how-write-once-read-many-worm-storage-works) must be satisfied. Do not set this policy by default. Usage: To search for registered cloud resources that have a retention policy, use `../registrations?preventKeyDeletion=true`.

totalCount

boolean

Response

200 - The list of registrations was successfully retrieved.

metadata

CollectionMetadataWithTotalCount

The metadata that describes the resource array.

resources

array

A collection of resources.

400 - The list of registrations could not be retrieved due to a malformed `urlEncodedResourceCRNQuery`, an invalid or missing request body, or a mismatch between the cloud service CRN and the resource CRN.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

403 -

429 -

500 -

Create an alias

POST /api/v2/keys/{id}/aliases/{alias}

Creates a unique alias for the specified key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.createalias

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets-alias.create

Request

Response

200 - An identical alias was previously created for the specified key.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

201 - A new alias was successfully created.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

400 - The alias could not be created due to a malformed `alias` or an invalid key ID.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - There are two possible causes for HTTP 404 while trying to create an alias, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_NOT_FOUND_ERR: The key with specified ID could not be found. INSTANCE_NOT_FOUND_ERR: Key alias could not be created, instance does not exist.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

409 - There are three possible causes for HTTP 409 while trying to create

an alias, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_ALIAS_QUOTA_ERR: The alias quota for this key or instance has been reached and alias can not be created.

KEY_RING_RESOURCE_QUOTA_ERR: Key alias could not be created, the resource quota for key rings in this instance has been reached and alais can not be created.

KEY_ALIAS_NOT_UNIQUE_ERR: The alias is already associated with a key in the specified instance.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

Delete an alias

DELETE /api/v2/keys/{id}/aliases/{alias}

Deletes an alias from the associated key.

Delete alias does not delete the key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.secrets.deletealias

Auditing

Calling this method generates the following auditing event.

hs-crypto.secrets-alias.delete

Request

Response

204 - An alias was successfully deleted. No content.

400 - The alias could not be deleted due to a malformed `alias` or an invalid key ID.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

404 - There are two possible causes for HTTP 404 while trying to delete an alias, specifying a reason code (resouces[0].reasons[0].code) as follows:

ALIAS_NOT_FOUND_ERR: The alias with specified key ID could not be found. INSTANCE_NOT_FOUND_ERR: Key alias could not be deleted, instance does not exist.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

429 -

500 -

List key rings

GET /api/v2/key_rings

List all key rings in the instance.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.keyrings.list

Auditing

Calling this method generates the following auditing event.

hs-crypto.key-rings.list

Request

Response

200 - The list of key rings was successfully retrieved.

metadata

CollectionMetadataWithTotalCount

The metadata that describes the resource array.

resources

array

A collection of resources.

400 -

401 -

429 -

500 -

Create a key ring

POST /api/v2/key_rings/{key-ring-id}

Create a key ring in the instance with the specified name. The key ring ID `default` is a reserved key ring ID and cannot be created nor destroyed. The `default` key ring is an initial key ring that is generated with each newly created instance. All keys not associated with an otherwise specified key ring exist within the default key ring.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.keyrings.create

Auditing

Calling this method generates the following auditing event.

hs-crypto.key-rings.create

Request

Response

201 - The key ring was successfully created.

204 - The key ring already exists. No content.

400 - The key ring could not be created due to invalid request data.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

409 - Key ring resource quota has been reached.

429 -

500 -

Delete key ring

DELETE /api/v2/key_rings/{key-ring-id}

Delete the key ring from the instance. The key ring ID `default` cannot be destroyed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

hs-crypto.keyrings.delete

Auditing

Calling this method generates the following auditing event.

hs-crypto.key-rings.delete

Request

Path Parameters

Query Parameters

force

boolean

Force delete the key ring. All keys in the key ring are required to be deleted (in state `5`) before this action can be performed. If the key ring to be deleted contains keys, they will be moved to the `default` key ring which requires the `kms.secrets.patch` IAM action.

Response

204 - The key ring was successfully deleted. No content.

400 - The key ring could not be deleted due to invalid request data.

metadata

CollectionMetadata

The metadata that describes the resource array.

resources

array

A collection of resources.

401 -

409 - There are two possible causes for HTTP 409 while trying to delete a key ring, specifying a reason code (resouces[0].reasons[0].code) as follows:

KEY_RING_NOT_EMPTY_ERR: The specified key ring contains at least one key (in any state). KEY_RING_KEYS_NOT_DELETED_ERR: (If `force` is set to `true`) The specified key ring contains at least one non-deleted key.