vaults

Creates, updates, deletes, gets or lists a vaults resource.

Overview

Name	`vaults`
Type	Resource
Id	`oci.kms.vaults`

Fields

The following fields are returned by SELECT queries:

get
list

The specified vault.

Name	Datatype	Description
`id`	`string`	The OCID of the vault.
`compartmentId`	`string`	The OCID of the compartment that contains this vault.
`cryptoEndpoint`	`string`	The service endpoint to perform cryptographic operations against. Cryptographic operations include [Encrypt](/api/#/en/key/latest/EncryptedData/Encrypt), [Decrypt](/api/#/en/key/latest/DecryptedData/Decrypt), and [GenerateDataEncryptionKey](/api/#/en/key/latest/GeneratedKey/GenerateDataEncryptionKey) operations.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`displayName`	`string`	A user-friendly name for the vault. It does not have to be unique, and it is changeable. Avoid entering confidential information.
`externalKeyManagerMetadataSummary`	`object`	Summary about metadata of external key manager to be returned to the customer as a response.
`freeformTags`	`object`	Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`isPrimary`	`boolean`	A Boolean value that indicates whether the Vault is primary Vault or replica Vault.
`lifecycleState`	`string`	The vault's current lifecycle state. Example: `DELETED` (CREATING, ACTIVE, DELETING, DELETED, PENDING_DELETION, SCHEDULING_DELETION, CANCELLING_DELETION, UPDATING, BACKUP_IN_PROGRESS, RESTORING)
`managementEndpoint`	`string`	The service endpoint to perform management operations against. Management operations include "Create," "Update," "List," "Get," and "Delete" operations.
`replicaDetails`	`object`	Vault replica details
`restoredFromVaultId`	`string`	The OCID of the vault from which this vault was restored, if it was restored from a backup file. If you restore a vault to the same region, the vault retains the same OCID that it had when you backed up the vault.
`timeCreated`	`string (date-time)`	The date and time this vault was created, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2018-04-03T21:10:29.600Z`
`timeOfDeletion`	`string (date-time)`	An optional property to indicate when to delete the vault, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2018-04-03T21:10:29.600Z`
`vaultType`	`string`	The type of vault. Each type of vault stores the key with different degrees of isolation and has different options and pricing. (VIRTUAL_PRIVATE, DEFAULT, EXTERNAL)
`wrappingkeyId`	`string`	The OCID of the vault's wrapping key.

The details of the Vault.

Name	Datatype	Description
`id`	`string`	The OCID of a vault.
`compartmentId`	`string`	The OCID of the compartment that contains a particular vault.
`cryptoEndpoint`	`string`	The service endpoint to perform cryptographic operations against. Cryptographic operations include [Encrypt](/api/#/en/key/latest/EncryptedData/Encrypt), [Decrypt](/api/#/en/key/latest/DecryptedData/Decrypt), and [GenerateDataEncryptionKey](/api/#/en/key/latest/GeneratedKey/GenerateDataEncryptionKey) operations.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`displayName`	`string`	A user-friendly name for a vault. It does not have to be unique, and it is changeable. Avoid entering confidential information.
`externalKeyManagerMetadataSummary`	`object`	Summary about metadata of external key manager to be returned to the customer as a response.
`freeformTags`	`object`	Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`lifecycleState`	`string`	A vault's current lifecycle state. Example: `ACTIVE` (CREATING, ACTIVE, DELETING, DELETED, PENDING_DELETION, SCHEDULING_DELETION, CANCELLING_DELETION, UPDATING, BACKUP_IN_PROGRESS, RESTORING)
`managementEndpoint`	`string`	The service endpoint to perform management operations against. Management operations include "Create," "Update," "List," "Get," and "Delete" operations.
`timeCreated`	`string (date-time)`	The date and time a vault was created, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2018-04-03T21:10:29.600Z`
`vaultType`	`string`	The type of vault. Each type of vault stores keys with different degrees of isolation and has different options and pricing. (VIRTUAL_PRIVATE, EXTERNAL, DEFAULT)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`vaultId`, `region`	`opc-request-id`	Gets the specified vault's configuration information.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning read operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />read operations exceeds 10 requests per second for a given tenancy.<br />
`list`	`select`	`compartmentId`, `region`	`limit`, `page`, `opc-request-id`, `sortBy`, `sortOrder`	Lists the vaults in the specified compartment.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning read operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />read operations exceeds 10 requests per second for a given tenancy.<br />
`create`	`insert`	`region`, `compartmentId`, `displayName`, `vaultType`	`opc-request-id`, `opc-retry-token`	Creates a new vault. The type of vault you create determines key placement, pricing, and<br />available options. Options include storage isolation, a dedicated service endpoint instead<br />of a shared service endpoint for API calls, and either a dedicated hardware security module<br />(HSM) or a multitenant HSM.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning write operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />write operations exceeds 10 requests per second for a given tenancy.<br />
`update`	`update`	`vaultId`, `region`	`if-match`, `opc-request-id`	Updates the properties of a vault. Specifically, you can update the<br />`displayName`, `freeformTags`, and `definedTags` properties. Furthermore,<br />the vault must be in an ACTIVE or CREATING state to be updated.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning write operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />write operations exceeds 10 requests per second for a given tenancy.<br />
`restore_vault_from_file`	`exec`	`compartmentId`, `content-length`, `region`	`if-match`, `content-md5`, `opc-request-id`, `opc-retry-token`	Restores a vault from an encrypted backup file. If a vault<br />with the same OCID already exists, this operation returns a response with a<br />409 HTTP status error code.<br />
`restore_vault_from_object_store`	`exec`	`compartmentId`, `region`	`if-match`, `opc-request-id`, `opc-retry-token`	Restores a vault from an encrypted backup file stored in Oracle Cloud Infrastructure Object<br />Storage. If a vault with the same OCID already exists, this operation returns<br />a response with a 409 HTTP status error code.<br />
`backup_vault`	`exec`	`vaultId`, `region`	`if-match`, `opc-request-id`, `opc-retry-token`	Backs up an encrypted file that contains all the metadata of a vault so that you can restore the vault later.<br />You can backup a vault whether or not it contains keys. This operation only backs up the<br />metadata of the vault, and does not include key metadata.<br />
`cancel_vault_deletion`	`exec`	`vaultId`, `region`	`if-match`, `opc-request-id`, `opc-retry-token`	Cancels the scheduled deletion of the specified vault. Canceling a scheduled deletion<br />restores the vault and all keys in it to their respective states from before their<br />scheduled deletion. All keys that were scheduled for deletion prior to vault<br />deletion retain their lifecycle state and time of deletion.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning write operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />write operations exceeds 10 requests per second for a given tenancy.<br />
`change_compartment`	`exec`	`vaultId`, `region`, `compartmentId`	`if-match`, `opc-request-id`, `opc-retry-token`	Moves a vault into a different compartment within the same tenancy. For information about<br />moving resources between compartments, see [Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br /><br />When provided, if-match is checked against the ETag values of the resource.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning write operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />write operations exceeds 10 requests per second for a given tenancy.<br />
`delete_vault_replica`	`exec`	`vaultId`, `region`, `replicaRegion`	`if-match`, `opc-request-id`, `opc-retry-token`	Deletes a vault replica<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning write operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />write operations exceeds 10 requests per second for a given tenancy.<br />
`schedule_vault_deletion`	`exec`	`vaultId`, `region`	`if-match`, `opc-request-id`, `opc-retry-token`	Schedules the deletion of the specified vault. This sets the lifecycle state of the vault and all keys in it<br />that are not already scheduled for deletion to `PENDING_DELETION` and then deletes them after the<br />retention period ends. The lifecycle state and time of deletion for keys already scheduled for deletion won't<br />change. If any keys in the vault are scheduled to be deleted after the specified time of<br />deletion for the vault, the call is rejected with the error code 409.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning write operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />write operations exceeds 10 requests per second for a given tenancy.<br />

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`compartmentId`	`string`	The OCID of the compartment.
`content-length`	`integer (int64)`	The content length of the body.
`region`	`string`	OCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
`vaultId`	`string`	The OCID of the vault.
`content-md5`	`string`	The base64-encoded MD5 hash value of the body, as described in [RFC 2616](https://tools.ietf.org/rfc/rfc2616), section 14.15. If the Content-MD5 header is present, Key Management performs an integrity check on the body of the HTTP request by computing the MD5 hash for the body and comparing it to the MD5 hash supplied in the header. If the two hashes don't match, the object is rejected and a response with 400 Unmatched Content MD5 error is returned, along with the message: "The computed MD5 of the request body (ACTUAL_MD5) does not match the Content-MD5 header (HEADER_MD5)."
`if-match`	`string`	For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
`limit`	`integer`	The maximum number of items to return in a paginated "List" call.
`opc-request-id`	`string`	Unique identifier for the request. If provided, the returned request ID will include this value. Otherwise, a random request ID will be generated by the service.
`opc-retry-token`	`string`	A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
`page`	`string`	The value of the `opc-next-page` response header from the previous "List" call.
`sortBy`	`string`	The field to sort by. You can specify only one sort order. The default order for `TIMECREATED` is descending. The default order for `DISPLAYNAME` is ascending.
`sortOrder`	`string`	The sort order to use, either ascending (`ASC`) or descending (`DESC`).

`SELECT` examples

get
list

Gets the specified vault's configuration information. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning read operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning read operations exceeds 10 requests per second for a given tenancy.

SELECT
id,
compartmentId,
cryptoEndpoint,
definedTags,
displayName,
externalKeyManagerMetadataSummary,
freeformTags,
isPrimary,
lifecycleState,
managementEndpoint,
replicaDetails,
restoredFromVaultId,
timeCreated,
timeOfDeletion,
vaultType,
wrappingkeyId
FROM oci.kms.vaults
WHERE vaultId = '{{ vaultId }}' -- required
AND region = '{{ region }}' -- required
AND opc-request-id = '{{ opc-request-id }}'
;

Lists the vaults in the specified compartment. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning read operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning read operations exceeds 10 requests per second for a given tenancy.

SELECT
id,
compartmentId,
cryptoEndpoint,
definedTags,
displayName,
externalKeyManagerMetadataSummary,
freeformTags,
lifecycleState,
managementEndpoint,
timeCreated,
vaultType
FROM oci.kms.vaults
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND opc-request-id = '{{ opc-request-id }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
;

`INSERT` examples

create
Manifest

Creates a new vault. The type of vault you create determines key placement, pricing, and available options. Options include storage isolation, a dedicated service endpoint instead of a shared service endpoint for API calls, and either a dedicated hardware security module (HSM) or a multitenant HSM. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning write operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning write operations exceeds 10 requests per second for a given tenancy.

INSERT INTO oci.kms.vaults (
compartmentId,
definedTags,
displayName,
externalKeyManagerMetadata,
freeformTags,
vaultType,
region,
opc-request-id,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}' /* required */,
'{{ externalKeyManagerMetadata }}',
'{{ freeformTags }}',
'{{ vaultType }}' /* required */,
'{{ region }}',
'{{ opc-request-id }}',
'{{ opc-retry-token }}'
RETURNING
id,
compartmentId,
cryptoEndpoint,
definedTags,
displayName,
externalKeyManagerMetadataSummary,
freeformTags,
isPrimary,
lifecycleState,
managementEndpoint,
replicaDetails,
restoredFromVaultId,
timeCreated,
timeOfDeletion,
vaultType,
wrappingkeyId
;

# Description fields are for documentation purposes
- name: vaults
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the vaults resource.
  - name: compartmentId
    value: "{{ compartmentId }}"
    description: |
      The OCID of the compartment where you want to create this vault.
  - name: definedTags
    value: "{{ definedTags }}"
    description: |
      Defined tags for this resource. Each key is predefined and scoped to a namespace.
      For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Operations": {"CostCenter": "42"}}`
  - name: displayName
    value: "{{ displayName }}"
    description: |
      A user-friendly name for the vault. It does not have to be unique, and it is changeable.
      Avoid entering confidential information.
  - name: externalKeyManagerMetadata
    description: |
      Metadata required for accessing External Key manager
    value:
      externalVaultEndpointUrl: "{{ externalVaultEndpointUrl }}"
      oauthMetadata:
        clientAppId: "{{ clientAppId }}"
        clientAppSecret: "{{ clientAppSecret }}"
        idcsAccountNameUrl: "{{ idcsAccountNameUrl }}"
      privateEndpointId: "{{ privateEndpointId }}"
  - name: freeformTags
    value: "{{ freeformTags }}"
    description: |
      Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace.
      For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Department": "Finance"}`
  - name: vaultType
    value: "{{ vaultType }}"
    description: |
      The type of vault to create. Each type of vault stores the key with different degrees of isolation and has different options and pricing.
    valid_values: ['VIRTUAL_PRIVATE', 'DEFAULT', 'EXTERNAL']
  - name: opc-request-id
    value: "{{ opc-request-id }}"
    description: Unique identifier for the request. If provided, the returned request ID will include this value. Otherwise, a random request ID will be generated by the service. 
    description: Unique identifier for the request. If provided, the returned request ID will include this value. Otherwise, a random request ID will be generated by the service. 
  - name: opc-retry-token
    value: "{{ opc-retry-token }}"
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 

`UPDATE` examples

update

Updates the properties of a vault. Specifically, you can update the displayName, freeformTags, and definedTags properties. Furthermore, the vault must be in an ACTIVE or CREATING state to be updated. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning write operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning write operations exceeds 10 requests per second for a given tenancy.

UPDATE oci.kms.vaults
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}'
WHERE 
vaultId = '{{ vaultId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND opc-request-id = '{{ opc-request-id}}'
RETURNING
id,
compartmentId,
cryptoEndpoint,
definedTags,
displayName,
externalKeyManagerMetadataSummary,
freeformTags,
isPrimary,
lifecycleState,
managementEndpoint,
replicaDetails,
restoredFromVaultId,
timeCreated,
timeOfDeletion,
vaultType,
wrappingkeyId;

Lifecycle Methods

Restores a vault from an encrypted backup file. If a vault with the same OCID already exists, this operation returns a response with a 409 HTTP status error code.

EXEC oci.kms.vaults.restore_vault_from_file 
@compartmentId='{{ compartmentId }}' --required, 
@content-length='{{ content-length }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@content-md5='{{ content-md5 }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}'
;

Restores a vault from an encrypted backup file stored in Oracle Cloud Infrastructure Object Storage. If a vault with the same OCID already exists, this operation returns a response with a 409 HTTP status error code.

EXEC oci.kms.vaults.restore_vault_from_object_store 
@compartmentId='{{ compartmentId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"backupLocation": "{{ backupLocation }}"
}'
;

Backs up an encrypted file that contains all the metadata of a vault so that you can restore the vault later. You can backup a vault whether or not it contains keys. This operation only backs up the metadata of the vault, and does not include key metadata.

EXEC oci.kms.vaults.backup_vault 
@vaultId='{{ vaultId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"backupLocation": "{{ backupLocation }}", 
"isIncludeKeys": {{ isIncludeKeys }}
}'
;

Cancels the scheduled deletion of the specified vault. Canceling a scheduled deletion restores the vault and all keys in it to their respective states from before their scheduled deletion. All keys that were scheduled for deletion prior to vault deletion retain their lifecycle state and time of deletion. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning write operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning write operations exceeds 10 requests per second for a given tenancy.

EXEC oci.kms.vaults.cancel_vault_deletion 
@vaultId='{{ vaultId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}'
;

Moves a vault into a different compartment within the same tenancy. For information about moving resources between compartments, see [Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes). When provided, if-match is checked against the ETag values of the resource. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning write operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning write operations exceeds 10 requests per second for a given tenancy.

EXEC oci.kms.vaults.change_compartment 
@vaultId='{{ vaultId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;

Deletes a vault replica As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning write operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning write operations exceeds 10 requests per second for a given tenancy.

EXEC oci.kms.vaults.delete_vault_replica 
@vaultId='{{ vaultId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"replicaRegion": "{{ replicaRegion }}"
}'
;

Schedules the deletion of the specified vault. This sets the lifecycle state of the vault and all keys in it that are not already scheduled for deletion to PENDING_DELETION and then deletes them after the retention period ends. The lifecycle state and time of deletion for keys already scheduled for deletion won't change. If any keys in the vault are scheduled to be deleted after the specified time of deletion for the vault, the call is rejected with the error code 409. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning write operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning write operations exceeds 10 requests per second for a given tenancy.

EXEC oci.kms.vaults.schedule_vault_deletion 
@vaultId='{{ vaultId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"timeOfDeletion": "{{ timeOfDeletion }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

Lifecycle Methods​