> ## Documentation Index
> Fetch the complete documentation index at: https://keyring.docs.composio.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# KMS and Vault adapters

> Configure AWS KMS, GCP Cloud KMS, HashiCorp Vault, and local development 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](/deployment/aws_ecs). `runtime_environment`
means the ECS task role supplies short-lived credentials; the configuration contains only key ARNs.

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/deployment/gcp_cloud_run). Metadata auth
uses the Cloud Run service identity and avoids a service-account private key.

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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  |

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

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

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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  |

<AccordionGroup>
  <Accordion title="token">
    `{ "method": "token", "token": "..." }`. Simple but long-lived; use a narrowly scoped renewable token and external rotation.
  </Accordion>

  <Accordion title="approle">
    Requires `role_id` and `secret_id`; `mount` defaults to `approle`. Keyring exchanges them for a client token during adapter initialization.
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

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

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.