Methods

Custom Headers

• Bluemix-Instance

  Required*

  string

  The IBM Cloud instance ID that identifies your Key Protect service instance.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• Correlation-Id

  string

  The v4 UUID used to correlate and track transactions.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• Prefer

  string

  Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

  Allowable values: [return=representation,return=minimal]

  Possible values: 14 ≤ length ≤ 21

• X-Kms-Key-Ring

  string

  The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

  Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

  Default: default

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "A Key Protect key",
      "extractable": false
    }
  ]
}

• metadata

  Required*
  CollectionMetadata

• resources

  Required*

  A collection of resources.

  Possible values: number of items = 1

  CreateKey[]

• metadata

  CollectionMetadata

• resources

  A collection of resources.

  Possible values: number of items = 1

  KeyWithPayload[]

Status Code

• 201

  The key was successfully created.

• 400

  The key is missing a required field.

• 401

  Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

• 403

  Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

• 404

  There are three possible causes for HTTP 404 while trying to create a key, specifying a reason code (resouces[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. Key Protect only permits the creation or import of keys in your Key Protect 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.

• 429

  Too many requests. Wait a few minutes and try again.

• 500

  IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Custom Headers

• Bluemix-Instance

  Required*

  string

  The IBM Cloud instance ID that identifies your Key Protect service instance.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• Correlation-Id

  string

  The v4 UUID used to correlate and track transactions.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• X-Kms-Key-Ring

  string

  The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

  Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

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.

  Possible values: 1 ≤ value ≤ 5000

  Default: 200

• 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.

  Possible values: value ≥ 0

  Default: 0

• state

  integer[]

  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.

  Allowable values: [0,1,2,3,5]

  Possible values: 0 ≤ number of items ≤ 5, 0 ≤ value ≤ 5

  Default: [0,1,2,3]

• 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:

  • foobar - find keys where the name or any of its aliases contain foobar, case insentive (i.e. matches xfoobar, Foobar).
  • fadedbee-0000-0000-0000-1234567890ab (a valid key id) - find keys where the id the key is fadedbee-0000-0000-0000-1234567890ab, or the name or any of its aliases contain fadedbee-0000-0000-0000-1234567890ab, case insentive.

  May prepend with options:

  • not: = when specified, inverts matching logic (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

  May prepend with search scopes:

  • alias: = search in key aliases for search query
  • name: = search in key names for search query

  Examples:

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

  Note:

  By default, if no scopes are provided, search will be performed in both name and alias 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 'KEY_SEARCH_TOO_BROAD'. Use the following filters to reduce the initial searchable space:

  • state (query parameter)
  • extractable (query parameter)
  • X-Kms-Key-Ring (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 alias 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 incompleteSearch will be true.

  When providing a fully specified key id or when searching within the alias 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.

  Possible values: 0 ≤ length ≤ 256, Value must match regular expression ^.{0,256}$

• 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.

  Allowable values: [id,state,extractable,imported,creationDate,lastUpdateDate,lastRotateDate,deletionDate,expirationDate]

  Possible values: 2 ≤ length ≤ 14

  Default: id

• 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: = = - 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: =: 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: “2000-03-21T00:00:00Z”
  • deletionDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • expirationDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • extractable
    • Boolean true or false without quotes, case-insensitive
  • lastRotateDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • lastUpdateDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • state
    • A list of comma-separated integers with no space in between: 0,1,2,3,5 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).

  Possible values: 0 ≤ length ≤ 512, Value must match regular expression ^.{0,512}$

• metadata

  Always included*

  The metadata that describes the list keys response

  CollectionMetadataListKeys

• resources

  A collection of resources.

  Possible values: 0 ≤ number of items ≤ 5000

  KeyFullRepresentation[]

Status Code

• 200

  The list of keys was successfully retrieved.

• 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

  Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

• 429

  Too many requests. Wait a few minutes and try again.

• 500

  IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Custom Headers

• Bluemix-Instance

  Required*

  string

  The IBM Cloud instance ID that identifies your Key Protect service instance.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• Correlation-Id

  string

  The v4 UUID used to correlate and track transactions.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• X-Kms-Key-Ring

  string

  The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

  Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

Query Parameters

• state

  integer[]

  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.

  Allowable values: [0,1,2,3,5]

  Possible values: 0 ≤ number of items ≤ 5, 0 ≤ value ≤ 5

  Default: [0,1,2,3]

• 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.

• 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: = = - 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: =: 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: “2000-03-21T00:00:00Z”
  • deletionDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • expirationDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • extractable
    • Boolean true or false without quotes, case-insensitive
  • lastRotateDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • lastUpdateDate
    • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
  • state
    • A list of comma-separated integers with no space in between: 0,1,2,3,5 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).

  Possible values: 0 ≤ length ≤ 512, Value must match regular expression ^.{0,512}$

Response Headers

• Key-Total

  integer

  The number of keys in your service instance.

  Possible values: value ≥ 0

Status Code

• 200

  The metadata was successfully retrieved.

• 401

  Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

• 403

  Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

• 429

  Too many requests. Wait a few minutes and try again.

• 500

  IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Custom Headers

• Bluemix-Instance

  Required*

  string

  The IBM Cloud instance ID that identifies your Key Protect service instance.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• Correlation-Id

  string

  The v4 UUID used to correlate and track transactions.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• Prefer

  string

  Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

  Allowable values: [return=representation,return=minimal]

  Possible values: 14 ≤ length ≤ 21

• X-Kms-Key-Ring

  string

  The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

  Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

  Default: default

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "A Key Protect key"
    }
  ]
}

• metadata

  Required*
  CollectionMetadata

• resources

  Required*

  A collection of resources.

  Possible values: number of items = 1

  CreateKeyWithPolicyOverrides[]

• metadata

  CollectionMetadata

• resources

  A collection of resources.

  Possible values: number of items = 1

  KeyWithPayload[]

Status Code

• 201

  The key was successfully created.

• 400

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

• 401

  Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

• 403

  Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

• 404

  There are three possible causes for HTTP 404 while trying to create a key, specifying a reason code (resouces[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. Key Protect only permits the creation or import of keys in your Key Protect 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.

• 429

  Too many requests. Wait a few minutes and try again.

• 500

  IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Custom Headers

• Bluemix-Instance

  Required*

  string

  The IBM Cloud instance ID that identifies your Key Protect service instance.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• Correlation-Id

  string

  The v4 UUID used to correlate and track transactions.

  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

• X-Kms-Key-Ring

  string

  The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

  Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

Path Parameters

• id

  Required*

  string

  The v4 UUID or alias that uniquely identifies the key.

  Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

• metadata

  Always included*

  The metadata that describes the resource array.

  CollectionMetadata

• resources

  Always included*

  A collection of resources.

  Possible values: number of items = 1

  KeyWithPayload[]

Status Code

• 200

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

• 400

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

• 401

  Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

• 403

  Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

• 404

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

• 429

  Too many requests. Wait a few minutes and try again.

• 500

  IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.