> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/activepieces/activepieces/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret Managers

> Integrate AWS Secrets Manager, HashiCorp Vault, and 1Password

Activepieces integrates with external secret managers to securely store and retrieve sensitive values like API keys, passwords, and tokens.

## Overview

Secret managers provide:

<CardGroup cols={3}>
  <Card title="Centralized Storage" icon="database">
    Store all secrets in one secure location
  </Card>

  <Card title="Access Control" icon="lock">
    Fine-grained permissions on secret access
  </Card>

  <Card title="Audit Trail" icon="list">
    Track who accessed which secrets when
  </Card>
</CardGroup>

## Supported Providers

Activepieces supports four secret manager providers:

<Tabs>
  <Tab title="AWS Secrets Manager">
    ### AWS Secrets Manager

    Store secrets in AWS with automatic rotation and IAM integration.

    **Features:**

    * Automatic secret rotation
    * IAM-based access control
    * Multi-region replication
    * CloudTrail audit logging

    **Best For:**

    * AWS-native deployments
    * Existing AWS infrastructure
    * Compliance requirements
  </Tab>

  <Tab title="HashiCorp Vault">
    ### HashiCorp Vault

    Enterprise-grade secret management with dynamic secrets.

    **Features:**

    * Dynamic secret generation
    * Encryption as a service
    * Multi-cloud support
    * Advanced policy engine

    **Best For:**

    * Multi-cloud deployments
    * Complex secret workflows
    * Dynamic credential management
  </Tab>

  <Tab title="1Password">
    ### 1Password

    User-friendly secret management with service accounts.

    **Features:**

    * Service account tokens
    * Simple secret references
    * Team collaboration
    * Browser integration

    **Best For:**

    * Small to medium teams
    * Simple secret management
    * Quick setup
  </Tab>

  <Tab title="CyberArk Conjur">
    ### CyberArk Conjur

    Enterprise privileged access management.

    **Features:**

    * Privileged access management
    * Policy-based access
    * Container security
    * DevOps integration

    **Best For:**

    * Enterprise security
    * Privileged access control
    * Complex compliance needs
  </Tab>
</Tabs>

## AWS Secrets Manager

### Configuration

<Steps>
  <Step title="Create IAM User">
    Create IAM user with Secrets Manager permissions:

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "secretsmanager:GetSecretValue",
            "secretsmanager:ListSecrets"
          ],
          "Resource": "*"
        }
      ]
    }
    ```
  </Step>

  <Step title="Generate Access Keys">
    Create access key ID and secret access key for the IAM user.
  </Step>

  <Step title="Configure in Activepieces">
    ```typescript theme={null}
    {
      providerId: SecretManagerProviderId.AWS,
      config: {
        accessKeyId: "AKIAIOSFODNN7EXAMPLE",
        secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        region: "us-east-1"
      }
    }
    ```
  </Step>
</Steps>

### Storing Secrets

Create secrets in AWS Secrets Manager:

```bash theme={null}
# Store secret as JSON
aws secretsmanager create-secret \
  --name prod/api-keys \
  --secret-string '{
    "slack_token": "xoxb-your-token",
    "github_token": "ghp_your-token"
  }'
```

### Referencing Secrets

Use the format: `secretName:jsonKey`

<CodeGroup>
  ```typescript In Flows theme={null}
  // Reference AWS secret
  const config = {
    apiKey: "{{aws|ap_sep_v1|prod/api-keys:slack_token}}"
  }
  ```

  ```bash Secret Format theme={null}
  {{aws|ap_sep_v1|prod/api-keys:slack_token}}
     ^^^           ^^^^^^^^^^^^^^^^^^^^^^^^^
   Provider ID    Secret path and key
  ```
</CodeGroup>

<Info>
  The `ap_sep_v1` separator is automatically added by Activepieces to identify secret references.
</Info>

### AWS Secret Structure

```json theme={null}
// Secrets must be stored as JSON objects
{
  "username": "admin",
  "password": "secure-password",
  "api_key": "key-value",
  "token": "token-value"
}
```

<Warning>
  AWS Secrets Manager returns the entire JSON object. You must specify the JSON key to extract a specific value.
</Warning>

## HashiCorp Vault

### Configuration

<Steps>
  <Step title="Enable AppRole Auth">
    ```bash theme={null}
    vault auth enable approle
    ```
  </Step>

  <Step title="Create Policy">
    ```bash theme={null}
    vault policy write activepieces - <<EOF
    path "secret/data/*" {
      capabilities = ["read", "list"]
    }
    path "sys/mounts" {
      capabilities = ["read"]
    }
    EOF
    ```
  </Step>

  <Step title="Create AppRole">
    ```bash theme={null}
    vault write auth/approle/role/activepieces \
      token_policies="activepieces" \
      token_ttl=1h \
      token_max_ttl=4h
    ```
  </Step>

  <Step title="Get Credentials">
    ```bash theme={null}
    # Get role ID
    vault read auth/approle/role/activepieces/role-id

    # Generate secret ID
    vault write -f auth/approle/role/activepieces/secret-id
    ```
  </Step>

  <Step title="Configure in Activepieces">
    ```typescript theme={null}
    {
      providerId: SecretManagerProviderId.HASHICORP,
      config: {
        url: "http://localhost:8200",
        roleId: "role-id-from-vault",
        secretId: "secret-id-from-vault",
        namespace: "optional-namespace"  // For Vault Enterprise
      }
    }
    ```
  </Step>
</Steps>

### Storing Secrets

Store secrets in KV v2 engine:

```bash theme={null}
# Enable KV v2 engine
vault secrets enable -path=secret kv-v2

# Store secret
vault kv put secret/prod/api-keys \
  slack_token="xoxb-your-token" \
  github_token="ghp_your-token"
```

### Referencing Secrets

Use the format: `mount/data/path/key`

<CodeGroup>
  ```typescript In Flows theme={null}
  // Reference Vault secret
  const config = {
    apiKey: "{{hashicorp|ap_sep_v1|secret/data/prod/api-keys/slack_token}}"
  }
  ```

  ```bash Path Format theme={null}
  {{hashicorp|ap_sep_v1|secret/data/prod/api-keys/slack_token}}
                          ^^^^^^ ^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
                          Mount  Data Path and Key
  ```
</CodeGroup>

<Info>
  For KV v2, the path must include `/data/` after the mount point. For KV v1, omit `/data/`.
</Info>

### Vault Path Structure

```
secret/                    # Mount path
  data/                    # KV v2 data path
    prod/                  # Folder
      api-keys/            # Secret name
        slack_token        # Key within secret
        github_token       # Key within secret
```

### Namespace Support

For Vault Enterprise with namespaces:

```typescript theme={null}
{
  namespace: "team-a"  // Access secrets in specific namespace
}
```

## 1Password

### Configuration

<Steps>
  <Step title="Create Service Account">
    In 1Password, navigate to:

    1. Settings > Service Accounts
    2. Create New Service Account
    3. Grant vault access permissions
  </Step>

  <Step title="Get Service Account Token">
    Copy the service account token (starts with `ops_...`)
  </Step>

  <Step title="Configure in Activepieces">
    ```typescript theme={null}
    {
      providerId: SecretManagerProviderId.ONEPASSWORD,
      config: {
        serviceAccountToken: "ops_abc123..."
      }
    }
    ```
  </Step>
</Steps>

### Storing Secrets

Create items in 1Password vaults using the app or CLI:

```bash theme={null}
# Install 1Password CLI
brew install 1password-cli

# Create item
op item create --category=login \
  --vault=Production \
  --title="API Keys" \
  token=xoxb-your-token
```

### Referencing Secrets

Use 1Password's secret reference format: `op://vault/item/field`

<CodeGroup>
  ```typescript In Flows theme={null}
  // Reference 1Password secret
  const config = {
    apiKey: "{{onepassword|ap_sep_v1|op://Production/API Keys/token}}"
  }
  ```

  ```bash Reference Format theme={null}
  {{onepassword|ap_sep_v1|op://Production/API Keys/token}}
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                           1Password secret reference
  ```
</CodeGroup>

### 1Password Reference Syntax

```
op://vault-name/item-name/field-name
    ^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^^^^
    Vault       Item      Field
```

**Examples:**

```
op://Production/Slack Credentials/api_token
op://Engineering/GitHub/personal_access_token
op://Shared/Database/password
```

<Warning>
  1Password secret references must exactly match the vault, item, and field names (case-sensitive).
</Warning>

## Using Secret Managers

### Connection Setup

<Tabs>
  <Tab title="Platform Admin">
    Configure secret managers at platform level:

    ```bash theme={null}
    POST /v1/secret-managers/connect
    ```

    ```json theme={null}
    {
      "providerId": "aws",
      "config": {
        "accessKeyId": "AKIA...",
        "secretAccessKey": "...",
        "region": "us-east-1"
      }
    }
    ```
  </Tab>

  <Tab title="Connection Status">
    Check connection status:

    ```bash theme={null}
    GET /v1/secret-managers
    ```

    ```json theme={null}
    {
      "data": [
        {
          "id": "aws",
          "name": "AWS Secrets Manager",
          "connection": {
            "configured": true,
            "connected": true
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Disconnect">
    Remove secret manager connection:

    ```bash theme={null}
    POST /v1/secret-managers/disconnect
    ```

    ```json theme={null}
    {
      "providerId": "aws"
    }
    ```
  </Tab>
</Tabs>

### Secret Resolution

Activepieces automatically resolves secret references:

```mermaid theme={null}
sequenceDiagram
    participant Flow
    participant Activepieces
    participant Cache
    participant SecretManager
    
    Flow->>Activepieces: Execute with {{secret reference}}
    Activepieces->>Activepieces: Parse secret reference
    Activepieces->>Cache: Check cache
    alt Cache hit
        Cache-->>Activepieces: Return cached value
    else Cache miss
        Activepieces->>SecretManager: Get secret value
        SecretManager-->>Activepieces: Return secret
        Activepieces->>Cache: Store in cache (TTL)
    end
    Activepieces->>Flow: Execute with resolved value
```

### Caching

Secret values are cached to reduce API calls:

* **Cache TTL**: 5 minutes (default)
* **Connection Status Cache**: 30 seconds
* **Cache Invalidation**: On configuration change

<Info>
  Caching improves performance but means secret changes may take up to 5 minutes to propagate.
</Info>

## Advanced Usage

### Nested Secret Resolution

Resolve secrets in nested objects:

```typescript theme={null}
// Configuration with multiple secrets
const config = {
  api: {
    key: "{{aws|ap_sep_v1|prod/keys:api_key}}",
    secret: "{{aws|ap_sep_v1|prod/keys:api_secret}}"
  },
  database: {
    password: "{{hashicorp|ap_sep_v1|secret/data/db/password}}"
  }
}

// Activepieces resolves all secrets recursively
```

### Conditional Resolution

Resolve only if value looks like a secret:

```typescript theme={null}
// This is resolved
const secret = "{{aws|ap_sep_v1|prod/keys:token}}"

// This is NOT resolved (missing braces)
const notSecret = "aws|ap_sep_v1|prod/keys:token"

// This is NOT resolved (plain text)
const plainText = "my-api-key"
```

### Error Handling

<AccordionGroup>
  <Accordion title="Secret Not Found">
    ```typescript theme={null}
    // Error code: SECRET_MANAGER_GET_SECRET_FAILED
    {
      "message": "Secret value for key token not found",
      "provider": "aws",
      "request": {
        "path": "prod/keys:token"
      }
    }
    ```

    **Resolution:**

    * Verify secret exists in secret manager
    * Check secret path is correct
    * Ensure JSON key exists (AWS)
  </Accordion>

  <Accordion title="Connection Failed">
    ```typescript theme={null}
    // Error code: SECRET_MANAGER_CONNECTION_FAILED
    {
      "message": "No token received",
      "provider": "hashicorp"
    }
    ```

    **Resolution:**

    * Verify credentials are correct
    * Check network connectivity
    * Review secret manager logs
  </Accordion>

  <Accordion title="Invalid Format">
    ```typescript theme={null}
    // Error code: VALIDATION
    {
      "message": "Wrong key format. Should be secretName:secretJsonKey"
    }
    ```

    **Resolution:**

    * Check secret reference format
    * AWS: Use `secretName:jsonKey`
    * Vault: Use `mount/data/path/key`
    * 1Password: Use `op://vault/item/field`
  </Accordion>
</AccordionGroup>

## Security Considerations

### Credential Security

<CardGroup cols={2}>
  <Card title="Encrypt at Rest" icon="lock">
    Secret manager credentials are encrypted using AES-256-GCM in the database.
  </Card>

  <Card title="Least Privilege" icon="shield">
    Grant only necessary permissions:

    * AWS: `GetSecretValue`, `ListSecrets`
    * Vault: Read access to specific paths
    * 1Password: Limited vault access
  </Card>

  <Card title="Credential Rotation" icon="rotate">
    Rotate secret manager credentials regularly:

    * AWS: Every 90 days
    * Vault: AppRole secret IDs monthly
    * 1Password: Service account tokens quarterly
  </Card>

  <Card title="Audit Logging" icon="list">
    Enable audit logs in your secret manager:

    * AWS CloudTrail
    * Vault audit devices
    * 1Password activity log
  </Card>
</CardGroup>

### Best Practices

<Steps>
  <Step title="Use Dedicated Credentials">
    Create dedicated IAM users/roles for Activepieces, not personal credentials.
  </Step>

  <Step title="Scope Permissions">
    Limit access to only secrets needed by Activepieces.
  </Step>

  <Step title="Monitor Access">
    Review secret manager audit logs for unusual access patterns.
  </Step>

  <Step title="Test Connection">
    Always test secret manager connection before deploying to production.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Test Fails">
    **AWS:**

    * Verify IAM credentials are correct
    * Check IAM permissions include `secretsmanager:ListSecrets`
    * Ensure region is correct

    **Vault:**

    * Verify Vault URL is accessible
    * Check AppRole credentials are valid
    * Ensure policy grants `sys/mounts` read permission

    **1Password:**

    * Verify service account token is valid
    * Check service account has vault access
    * Ensure token hasn't expired
  </Accordion>

  <Accordion title="Secrets Not Resolving">
    **Check:**

    1. Secret reference format is correct
    2. Secret exists in secret manager
    3. Connection is still active
    4. Cache hasn't expired (wait 5 minutes)
    5. No recent configuration changes
  </Accordion>

  <Accordion title="Performance Issues">
    **Solutions:**

    * Increase cache TTL (requires code change)
    * Use secrets sparingly in high-frequency flows
    * Deploy secret manager close to Activepieces
    * Monitor secret manager API limits
  </Accordion>
</AccordionGroup>

## API Reference

<CodeGroup>
  ```bash Connect Secret Manager theme={null}
  curl -X POST 'https://api.activepieces.com/v1/secret-managers/connect' \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "providerId": "aws",
      "config": {
        "accessKeyId": "AKIA...",
        "secretAccessKey": "...",
        "region": "us-east-1"
      }
    }'
  ```

  ```bash List Providers theme={null}
  curl -X GET 'https://api.activepieces.com/v1/secret-managers' \
    -H 'Authorization: Bearer {token}'
  ```

  ```bash Disconnect theme={null}
  curl -X POST 'https://api.activepieces.com/v1/secret-managers/disconnect' \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "providerId": "aws"
    }'
  ```
</CodeGroup>

## Migration Guide

### Moving from Environment Variables

<Steps>
  <Step title="Identify Secrets">
    List all secrets currently in environment variables or connection configs.
  </Step>

  <Step title="Store in Secret Manager">
    Create secrets in your chosen secret manager:

    ```bash theme={null}
    # AWS example
    aws secretsmanager create-secret \
      --name prod/slack \
      --secret-string '{"token":"xoxb-..."}'  
    ```
  </Step>

  <Step title="Update Connections">
    Replace hardcoded values with secret references:

    Before:

    ```typescript theme={null}
    { token: "xoxb-hardcoded-token" }
    ```

    After:

    ```typescript theme={null}
    { token: "{{aws|ap_sep_v1|prod/slack:token}}" }
    ```
  </Step>

  <Step title="Test & Verify">
    Test connections work with secret manager integration.
  </Step>

  <Step title="Remove Old Secrets">
    Remove hardcoded secrets from environment variables.
  </Step>
</Steps>

## Related Topics

<CardGroup cols={3}>
  <Card title="Security Practices" icon="shield" href="/admin/security-practices">
    General security guidelines
  </Card>

  <Card title="Audit Logs" icon="list" href="/admin/audit-logs">
    Track secret access
  </Card>

  <Card title="Environment Setup" icon="gear" href="/deployment/environment-variables">
    Configure deployment
  </Card>
</CardGroup>