Secret Managers - Activepieces

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

Overview

Secret managers provide:

Centralized Storage

Store all secrets in one secure location

Access Control

Fine-grained permissions on secret access

Audit Trail

Track who accessed which secrets when

Supported Providers

Activepieces supports four secret manager providers:

AWS Secrets Manager
HashiCorp Vault
1Password
CyberArk Conjur

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

AWS Secrets Manager

Configuration

Create IAM User

Create IAM user with Secrets Manager permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:ListSecrets"
      ],
      "Resource": "*"
    }
  ]
}

Generate Access Keys

Create access key ID and secret access key for the IAM user.

Configure in Activepieces

{
  providerId: SecretManagerProviderId.AWS,
  config: {
    accessKeyId: "AKIAIOSFODNN7EXAMPLE",
    secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    region: "us-east-1"
  }
}

Storing Secrets

Create secrets in AWS Secrets Manager:

# 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

// Reference AWS secret
const config = {
  apiKey: "{{aws|ap_sep_v1|prod/api-keys:slack_token}}"
}

The ap_sep_v1 separator is automatically added by Activepieces to identify secret references.

AWS Secret Structure

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

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

HashiCorp Vault

Configuration

Enable AppRole Auth

vault auth enable approle

Create Policy

vault policy write activepieces - <<EOF
path "secret/data/*" {
  capabilities = ["read", "list"]
}
path "sys/mounts" {
  capabilities = ["read"]
}
EOF

Create AppRole

vault write auth/approle/role/activepieces \
  token_policies="activepieces" \
  token_ttl=1h \
  token_max_ttl=4h

Get Credentials

# Get role ID
vault read auth/approle/role/activepieces/role-id

# Generate secret ID
vault write -f auth/approle/role/activepieces/secret-id

Configure in Activepieces

{
  providerId: SecretManagerProviderId.HASHICORP,
  config: {
    url: "http://localhost:8200",
    roleId: "role-id-from-vault",
    secretId: "secret-id-from-vault",
    namespace: "optional-namespace"  // For Vault Enterprise
  }
}

Storing Secrets

Store secrets in KV v2 engine:

# 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

// Reference Vault secret
const config = {
  apiKey: "{{hashicorp|ap_sep_v1|secret/data/prod/api-keys/slack_token}}"
}

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

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:

{
  namespace: "team-a"  // Access secrets in specific namespace
}

1Password

Configuration

Create Service Account

In 1Password, navigate to:

Settings > Service Accounts
Create New Service Account
Grant vault access permissions

Get Service Account Token

Copy the service account token (starts with ops_...)

Configure in Activepieces

{
  providerId: SecretManagerProviderId.ONEPASSWORD,
  config: {
    serviceAccountToken: "ops_abc123..."
  }
}

Storing Secrets

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

# 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

// Reference 1Password secret
const config = {
  apiKey: "{{onepassword|ap_sep_v1|op://Production/API Keys/token}}"
}

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

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

Using Secret Managers

Connection Setup

Platform Admin
Connection Status
Disconnect

Configure secret managers at platform level:

POST /v1/secret-managers/connect

{
  "providerId": "aws",
  "config": {
    "accessKeyId": "AKIA...",
    "secretAccessKey": "...",
    "region": "us-east-1"
  }
}

Check connection status:

GET /v1/secret-managers

{
  "data": [
    {
      "id": "aws",
      "name": "AWS Secrets Manager",
      "connection": {
        "configured": true,
        "connected": true
      }
    }
  ]
}

Remove secret manager connection:

POST /v1/secret-managers/disconnect

{
  "providerId": "aws"
}

Secret Resolution

Activepieces automatically resolves secret references:

Caching

Secret values are cached to reduce API calls:

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

Caching improves performance but means secret changes may take up to 5 minutes to propagate.

Advanced Usage

Nested Secret Resolution

Resolve secrets in nested objects:

// 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:

// 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

Secret Not Found

// 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)

Connection Failed

// Error code: SECRET_MANAGER_CONNECTION_FAILED
{
  "message": "No token received",
  "provider": "hashicorp"
}

Resolution:

Verify credentials are correct
Check network connectivity
Review secret manager logs

Invalid Format

// 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

Security Considerations

Credential Security

Encrypt at Rest

Secret manager credentials are encrypted using AES-256-GCM in the database.

Least Privilege

Grant only necessary permissions:

AWS: GetSecretValue, ListSecrets
Vault: Read access to specific paths
1Password: Limited vault access

Credential Rotation

Rotate secret manager credentials regularly:

AWS: Every 90 days
Vault: AppRole secret IDs monthly
1Password: Service account tokens quarterly

Audit Logging

Enable audit logs in your secret manager:

AWS CloudTrail
Vault audit devices
1Password activity log

Best Practices

Use Dedicated Credentials

Create dedicated IAM users/roles for Activepieces, not personal credentials.

Scope Permissions

Limit access to only secrets needed by Activepieces.

Monitor Access

Review secret manager audit logs for unusual access patterns.

Test Connection

Always test secret manager connection before deploying to production.

Troubleshooting

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

Secrets Not Resolving

Check:

Secret reference format is correct
Secret exists in secret manager
Connection is still active
Cache hasn’t expired (wait 5 minutes)
No recent configuration changes

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

API Reference

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"
    }
  }'

Migration Guide

Moving from Environment Variables

Identify Secrets

List all secrets currently in environment variables or connection configs.

Store in Secret Manager

Create secrets in your chosen secret manager:

# AWS example
aws secretsmanager create-secret \
  --name prod/slack \
  --secret-string '{"token":"xoxb-..."}'  

Update Connections

Replace hardcoded values with secret references:Before:

{ token: "xoxb-hardcoded-token" }

After:

{ token: "{{aws|ap_sep_v1|prod/slack:token}}" }

Test & Verify

Test connections work with secret manager integration.

Remove Old Secrets

Remove hardcoded secrets from environment variables.

Security Practices

General security guidelines

Audit Logs

Track secret access

Environment Setup

Configure deployment

Platform Management

Security

​Overview

Centralized Storage

Access Control

Audit Trail

​Supported Providers

​AWS Secrets Manager

​HashiCorp Vault

​1Password

​CyberArk Conjur

​AWS Secrets Manager

​Configuration

​Storing Secrets

​Referencing Secrets

​AWS Secret Structure

​HashiCorp Vault

​Configuration

​Storing Secrets

​Referencing Secrets

​Vault Path Structure

​Namespace Support

​1Password

​Configuration

​Storing Secrets

​Referencing Secrets

​1Password Reference Syntax

​Using Secret Managers

​Connection Setup

​Secret Resolution

​Caching

​Advanced Usage

​Nested Secret Resolution

​Conditional Resolution

​Error Handling

​Security Considerations

​Credential Security

Encrypt at Rest

Least Privilege

Credential Rotation

Audit Logging

​Best Practices

​Troubleshooting

​API Reference

​Migration Guide

​Moving from Environment Variables

​Related Topics

Security Practices

Audit Logs

Environment Setup

Overview

Supported Providers

AWS Secrets Manager

HashiCorp Vault

1Password

CyberArk Conjur

AWS Secrets Manager

Configuration

Storing Secrets

Referencing Secrets

AWS Secret Structure

HashiCorp Vault

Configuration

Storing Secrets

Referencing Secrets

Vault Path Structure

Namespace Support

1Password

Configuration

Storing Secrets

Referencing Secrets

1Password Reference Syntax

Using Secret Managers

Connection Setup

Secret Resolution

Caching

Advanced Usage

Nested Secret Resolution

Conditional Resolution

Error Handling

Security Considerations

Credential Security

Best Practices

Troubleshooting

API Reference

Migration Guide

Moving from Environment Variables

Related Topics