KMS and Vault adapters

Use one provider consistently or mix providers by section. Adapter IDs are your stable envelope routing identifiers; changing a map key creates a new identity even if its provider settings are identical.

AWS KMS

Use this adapter on the preferred ECS/Fargate deployment. runtime_environment means the ECS task role supplies short-lived credentials; the configuration contains only key ARNs.

credential:
  active_adapter_id: aws-credential
  active_key_id: arn:aws:kms:us-east-1:111122223333:key/credential-key-id
  adapters:
    aws-credential:
      type: aws
      region: us-east-1
      credential_source: runtime_environment
      allowed_key_ids:
        - arn:aws:kms:us-east-1:111122223333:key/credential-key-id

authorization_gate:
  active_adapter_id: aws-gate
  active_key_id: arn:aws:kms:us-east-1:111122223333:key/gate-key-id
  adapters:
    aws-gate:
      type: aws
      region: us-east-1
      credential_source: runtime_environment
      allowed_key_ids:
        - arn:aws:kms:us-east-1:111122223333:key/gate-key-id

secret_transfer:
  active_kid: transfer-2026-01
  adapters:
    aws-transfer:
      type: aws
      region: us-east-1
      credential_source: runtime_environment
      keys:
        transfer-2026-01: arn:aws:kms:us-east-1:111122223333:key/transfer-key-id

dek_cache:
  capacity: 1024
  ttl_seconds: 300

Keep dek_cache enabled in production. It stores only non-extractable in-process key handles and avoids a KMS decrypt round trip for repeated use of the same Composio envelope. A cache loss causes another unwrap, not credential loss.

AWS fields

Field	Required	Meaning
`type`	Yes	`aws`
`region`	Yes	AWS signing and KMS region
`credential_source`	No	`static` by default, or `runtime_environment`
`access_key_id`	Static mode	Access-key ID
`secret_access_key`	Static mode	Secret key
`session_token`	No	Temporary-credential session token
`endpoint`	No	Alternate KMS API base URL, normally only for a reviewed emulator/private endpoint
`allowed_key_ids`	Symmetric only	Non-empty root-key ID/ARN allowlist
`keys`	Transfer only	Non-empty `kid` to asymmetric KMS key ID/ARN map

Static credential fields are rejected in runtime_environment mode. Runtime mode fails fast if it cannot resolve environment or container credentials. On ECS, attach the permissions to taskRoleArn, not the execution role. Required IAM permissions are kms:Encrypt and kms:Decrypt for symmetric roots, plus kms:GetPublicKey and kms:Decrypt for transfer keys. The transfer key must have KeyUsage=ENCRYPT_DECRYPT and support RSAES_OAEP_SHA_256.

GCP Cloud KMS

Use this adapter on the preferred Cloud Run deployment. Metadata auth uses the Cloud Run service identity and avoids a service-account private key.

credential:
  active_adapter_id: gcp-credential
  active_key_id: keyring-credential
  adapters:
    gcp-credential:
      type: gcp_cloud_kms
      project_id: customer-security
      location: global
      key_ring: keyring
      auth:
        method: metadata
      allowed_key_ids: [keyring-credential]

authorization_gate:
  active_adapter_id: gcp-gate
  active_key_id: keyring-authorization-gate
  adapters:
    gcp-gate:
      type: gcp_cloud_kms
      project_id: customer-security
      location: global
      key_ring: keyring
      auth:
        method: metadata
      allowed_key_ids: [keyring-authorization-gate]

secret_transfer:
  active_kid: transfer-2026-01
  adapters:
    gcp-transfer:
      type: gcp_cloud_kms
      auth:
        method: metadata
      keys:
        transfer-2026-01: projects/customer-security/locations/global/keyRings/keyring/cryptoKeys/keyring-transfer/cryptoKeyVersions/1

GCP fields

Field	Required	Meaning
`type`	Yes	`gcp_cloud_kms`
`project_id`	Symmetric only	Project containing the key ring
`location`	Symmetric only	Cloud KMS location
`key_ring`	Symmetric only	Key-ring name
`auth`	Yes	Authentication union described below
`endpoint`	No	Alternate Cloud KMS base URL
`allowed_key_ids`	Symmetric only	CryptoKey names relative to the configured key ring
`keys`	Transfer only	`kid` to full `cryptoKeyVersion` resource name map

metadata

{ "method": "metadata", "service_account_email": "optional@example.iam.gserviceaccount.com" }. Preferred on Cloud Run. Omit the email to use the service’s assigned identity.

service_account_key

Requires client_email and PEM private_key; token_uri defaults to https://oauth2.googleapis.com/token. Store the complete config as a secret.

service_account_key_file

Requires path to a service-account JSON file and is suitable only for the Node runtime. The file is read eagerly during configuration loading.

access_token

Requires a non-empty token. Use only with an external refresh/redeployment process because the config value itself does not rotate in place.

Grant the identity cloudkms.cryptoKeyVersions.useToEncrypt and useToDecrypt on symmetric keys. Transfer keys need cloudkms.cryptoKeyVersions.viewPublicKey and useToDecrypt. The transfer key version must use an RSA OAEP SHA-256 decrypt algorithm.

HashiCorp Vault Transit

credential:
  active_adapter_id: vault-credential
  active_key_id: keyring-credential
  adapters:
    vault-credential:
      type: hashicorp_vault
      address: https://vault.example.com
      namespace: customer
      mount: transit
      auth:
        method: kubernetes
        role: keyring
      allowed_key_ids: [keyring-credential]

authorization_gate:
  active_adapter_id: vault-gate
  active_key_id: keyring-authorization-gate
  adapters:
    vault-gate:
      type: hashicorp_vault
      address: https://vault.example.com
      namespace: customer
      mount: transit
      auth:
        method: kubernetes
        role: keyring
      allowed_key_ids: [keyring-authorization-gate]

secret_transfer:
  active_kid: transfer-2026-01
  adapters:
    vault-transfer:
      type: hashicorp_vault
      address: https://vault.example.com
      namespace: customer
      mount: transit
      auth:
        method: kubernetes
        role: keyring
      keys:
        transfer-2026-01: keyring-transfer

Vault fields

Field	Required	Meaning
`type`	Yes	`hashicorp_vault`
`address`	Yes	Vault server base URL
`namespace`	No	Vault Enterprise namespace
`mount`	No	Transit mount, default `transit`
`auth`	Yes	Token, AppRole, or Kubernetes authentication
`allowed_key_ids`	Symmetric only	Non-empty Transit key-name allowlist
`keys`	Transfer only	Non-empty `kid` to Transit RSA key-name map

token

{ "method": "token", "token": "..." }. Simple but long-lived; use a narrowly scoped renewable token and external rotation.

approle

Requires role_id and secret_id; mount defaults to approle. Keyring exchanges them for a client token during adapter initialization.

kubernetes

Requires role. Set jwt explicitly or let Keyring read token_path, which defaults to /var/run/secrets/kubernetes.io/serviceaccount/token; auth mount defaults to kubernetes.

Vault policy must allow encrypt/decrypt on the two symmetric Transit keys. The transfer adapter also reads the public-key metadata and decrypts with a pinned key version; configure a rsa-2048, rsa-3072, or rsa-4096 Transit key with decryption enabled.

Development-only adapters

credential:
  active_adapter_id: dev-credential
  active_key_id: dev-credential-key
  adapters:
    dev-credential:
      type: development_only_in_memory
      allowed_key_ids: [dev-credential-key]

authorization_gate:
  active_adapter_id: dev-gate
  active_key_id: dev-gate-key
  adapters:
    dev-gate:
      type: development_only_in_memory
      allowed_key_ids: [dev-gate-key]

secret_transfer:
  active_kid: dev-transfer-key
  adapters:
    dev-transfer:
      type: development_only_in_memory
      kids: [dev-transfer-key]

The symmetric adapter derives ephemeral in-process behavior and the transfer adapter generates an ephemeral RSA pair. Use this configuration only for local tests; it cannot provide durable decryption or safe multi-instance operation.

Get started

How Keyring works

Security

Deploy

Configure

Operate

KMS and Vault adapters

AWS KMS

AWS fields

GCP Cloud KMS

GCP fields

HashiCorp Vault Transit

Vault fields

Development-only adapters

​AWS KMS

​AWS fields

​GCP Cloud KMS

​GCP fields

​HashiCorp Vault Transit

​Vault fields

​Development-only adapters

AWS KMS

AWS fields

GCP Cloud KMS

GCP fields

HashiCorp Vault Transit

Vault fields

Development-only adapters