Skip to main content

Bring your own key (BYOK) Limited availability

Register, list, update, or delete your customer managed keys (CMKs) in Aiven projects using the Aiven API or the Aiven CLI.

important

Bring your own key (BYOK) is a limited availability feature. Contact Aiven to request access.

Prerequisites​

  • Key management service (KMS) that supports asymmetric RSA 2048 or RSA 4096 keys in Google Cloud, Oracle Cloud Infrastructure (OCI), Amazon Web Services (AWS), or Microsoft Azure

  • Authentication token to use the Aiven API

  • Aiven CLI installed and configured (for CLI instructions)

List CMK accessors​

List customer managed key (CMK) accessors - principals that need to be granted access to perform encrypt/decrypt operations on your behalf.

API endpoint​

GET /v1/project/PROJECT_ID/secrets/cmks/accessors

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier

Sample request​

curl -X GET https://api.aiven.io/v1/project/PROJECT_ID/secrets/cmks/accessors \
  -H "Authorization: Bearer AIVEN_API_TOKEN"

Sample response​

A successful request returns a 200 OK status code and a JSON object with the accessors for each provider, for example:

{
  "accessors": {
    "gcp": {
      "access_group": "access.example.12345678-1234-1234-1234-123456789abc@aiven.io"
    }
  }
}
note

For Google Cloud Key Management Service keys, grant the group in the access_group parameter the roles/cloudkms.cryptoOperator role.

Manage a project CMK​

Use the Aiven API or Aiven CLI to manage customer managed keys (CMKs) for encrypting service data.

Register CMK resource identifier​

Register a customer managed key resource identifier for an Aiven project.

API endpoint​

POST /v1/project/PROJECT_ID/secrets/cmks

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier

Request body parameters​

ParameterTypeRequiredDescription
providerStringTrueCloud provider hosting the KMS: aws, gcp, azure, or oci
resourceStringTrueCMK reference (key identifier of max 512 characters: AWS ARN, OCI OCID, Google Cloud resource name, or Azure key identifier)
default_cmkBooleanFalseMark this key as default for new service creation

Sample request (AWS)​

curl -X POST https://api.aiven.io/v1/project/PROJECT_ID/secrets/cmks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer AIVEN_API_TOKEN" \
  -d '{
        "provider": "aws",
        "resource": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234",
        "default_cmk": true
      }'

Sample response (AWS)​

A successful request returns a 201 CREATED status code and a JSON object representing the newly registered CMK configuration, for example:

{
  "cmk": {
    "id": "12345678-1234-1234-1234-12345678abcd",
    "provider": "aws",
    "default_cmk": true,
    "resource": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234",
    "status": "current",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

Response fields​

ParameterDescription
idIdentifier of the specific key
providerProvider type, one of gcp, aws, azure, or oci
resourceCMK reference
statusOne of current, old, or deleted
default_cmkWhether this CMK has been marked default for new services
created_atCMK creation timestamp
updated_atCMK update timestamp

Update CMK​

Update attributes or parameters on an existing customer managed key configuration.

API endpoint​

POST /v1/project/PROJECT_ID/secrets/cmks/CMK_ID

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier
CMK_IDStringTrueCMK identifier

Request body parameters​

ParameterTypeRequiredDescription
default_cmkBooleanFalseMark a specific key as default for new service creation

Sample request​

curl -X POST https://api.aiven.io/v1/project/PROJECT_ID/secrets/cmks/CMK_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer AIVEN_API_TOKEN" \
  -d '{
        "default_cmk": false
      }'

Sample response​

A successful request returns a 200 OK status code and a JSON object representing the updated CMK configuration, for example:

{
  "cmk": {
    "id": "12345678-1234-1234-1234-12345678abcd",
    "provider": "gcp",
    "default_cmk": false,
    "resource": "projects/aiven-example/locations/us-central1/keyRings/example-keyring/cryptoKeys/example-key",
    "status": "current",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

Response fields​

ParameterDescription
idIdentifier of the specific key
providerProvider type, one of gcp, aws, azure, or oci
resourceCMK reference
statusOne of current, old, or deleted
default_cmkWhether this CMK has been marked default for new services
created_atCMK creation timestamp
updated_atCMK update timestamp

Get CMK details​

Get the details of a customer managed key configuration.

API endpoint​

GET /v1/project/PROJECT_ID/secrets/cmks/CMK_ID

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier
CMK_IDStringTrueCMK identifier

Sample request​

curl -X GET https://api.aiven.io/v1/project/PROJECT_ID/secrets/cmks/CMK_ID \
  -H "Authorization: Bearer AIVEN_API_TOKEN"

Sample response (OCI)​

A successful request returns a 200 OK status code and a JSON object representing the specified CMK configuration, for example:

{
  "cmk": {
    "id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "provider": "oci",
    "default_cmk": false,
    "resource": "ocid1.key.oc1.iad.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "current",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

List CMKs​

List all customer managed key configurations for a project.

API endpoint​

GET /v1/project/PROJECT_ID/secrets/cmks

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier

Sample request​

curl -X GET https://api.aiven.io/v1/project/PROJECT_ID/secrets/cmks \
  -H "Authorization: Bearer AIVEN_API_TOKEN"

Sample response (OCI)​

A successful request returns a 200 OK status code and a JSON object containing a list of all CMK configurations for a project, for example:

{
  "cmks": [
    {
      "id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
      "provider": "oci",
      "default_cmk": false,
      "resource": "ocid1.key.oc1.iad.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "current",
      "created_at": "YYYY-MM-DDTHH:MM:SSZ",
      "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
    },
    {
      "id": "8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
      "provider": "oci",
      "default_cmk": false,
      "resource": "ocid1.key.oc1.phx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
      "status": "old",
      "created_at": "YYYY-MM-DDTHH:MM:SSZ",
      "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
    }
  ]
}

Remove CMK​

Delete a customer managed key configuration.

note

This function renders the services linked to the key inoperable. Migrate the services to either another CMK or Aiven managed keys to avoid any service disruption.

API endpoint​

DELETE /v1/project/PROJECT_ID/secrets/cmks/CMK_ID

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier
CMK_IDStringTrueCMK identifier

Sample request​

curl -X DELETE https://api.aiven.io/v1/project/PROJECT_ID/secrets/cmks/CMK_ID \
  -H "Authorization: Bearer AIVEN_API_TOKEN"

Sample response (OCI)​

A successful request returns a 200 OK status code and a JSON object representing the deleted CMK configuration, for example:

{
  "cmk": {
    "id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "provider": "oci",
    "default_cmk": false,
    "resource": "ocid1.key.oc1.iad.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "current",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}