Configuring an AWS Secrets Manager Connection

OneSchema integrates with AWS Secrets Manager to retrieve secrets at runtime for use in Multi FileFeed workflows. This keeps sensitive material — such as PGP decryption keys and passphrases — in your own AWS account rather than in OneSchema.

This guide walks you through:

1. Preparing your AWS IAM role
2. Creating an AWS Secrets Manager account (connection) in OneSchema
3. Adding managed secret references
4. Testing the connection

You can configure secrets manager connections via the OneSchema dashboard or via the API — this guide covers both.

How it works

sequenceDiagram
    participant Workflow as Multi FileFeed Workflow
    participant OS as OneSchema
    participant STS as AWS STS
    participant SM as AWS Secrets Manager

    Note over Workflow,SM: Runtime secret retrieval (e.g. Decrypt Files node)

    Workflow->>OS: Trigger node that needs a secret
    OS->>STS: AssumeRole (OneSchemaSecretsManagerReader)
    STS-->>OS: Temporary credentials (intermediate role)
    OS->>STS: AssumeRole (your secret-reader role,<br/>with External ID)
    STS-->>OS: Temporary credentials (customer role)
    OS->>SM: GetSecretValue (secret identifier, region)
    SM-->>OS: Secret value (plaintext)
    OS->>Workflow: Secret used in execution of a single node in a single node run
    Note over OS,SM: Secret value is never stored in OneSchema

• Create an IAM role in your AWS account authorized to read the secrets you want to use in OneSchema
• Configure its trust policy to allow it to be assumed by OneSchema's secrets reader role (OneSchemaSecretsManagerReader, whose ARN is supplied by your OneSchema account team)
• Create a connection in the OneSchema dashboard pointing to your role, and specify which secrets to make available to Decrypt Files nodes in your Multi FileFeed workflows

If you are already familiar with cross-account IAM role assumption, you may be able to skip ahead to Step 2 after setting up your role.

Prerequisites

• Admin role in your OneSchema organization (required to create and manage connections)
• The AWS Secrets Manager feature enabled for your organization (contact your OneSchema representative if you do not see the AWS Secrets Manager tab on the Connections page)
• An AWS account with one or more secrets already stored in AWS Secrets Manager
• The following AWS values on hand:

Step 1 — Prepare your AWS IAM role

OneSchema uses a role-chaining mechanism to access your secrets. You create a secret-reader role in your AWS account, and OneSchema's intermediate role (OneSchemaSecretsManagerReader) assumes it at runtime.

1a. Create the secret-reader role

Create an IAM role (e.g. OneSchemaFileDecryptionKeysReader) that will hold the secret-reading permissions.

We recommend setting MaxSessionDuration to 1 hour (3600 seconds) — the minimum AWS allows. OneSchema creates short-lived credentials for each secret read, so a short maximum session duration limits exposure.

1b. Configure the trust policy

Allow OneSchema's intermediate role to assume your secret-reader role. Obtain the OneSchemaSecretsManagerReader ARN from your OneSchema account team.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowOneSchemaToAssume",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<ONESCHEMA_ACCOUNT_ID>:role/OneSchemaSecretsManagerReader"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<EXTERNAL_ID>"
        }
      }
    }
  ]
}

External ID guidance: Use a cryptographically random string. Generate one with openssl rand -hex 32. A guessable external ID weakens confused-deputy protection.

Important: Use StringEquals, not ForAllValues:StringEquals. The ForAllValues set operator treats an absent key as vacuously true, which would allow callers that omit the external ID entirely.

1c. Attach a permissions policy

Grant the secret-reader role access to the specific secret(s):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadSecrets",
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
      "Resource": [
        "arn:aws:secretsmanager:<REGION>:<YOUR_ACCOUNT_ID>:secret:<SECRET_NAME>-*"
      ]
    }
  ]
}

If your secrets are encrypted with a customer-managed KMS key (rather than the default aws/secretsmanager key), also grant kms:Decrypt on that key's ARN.

DescribeSecret is used during connection validation. You can omit it for minimal access, but the Test Connection flow may return less informative error messages without it.

Storing secrets correctly

OneSchema expects secret values to be stored as raw plaintext in AWS Secrets Manager:

• PGP private key: Store the full key block starting with -----BEGIN PGP PRIVATE KEY BLOCK----- and ending with -----END PGP PRIVATE KEY BLOCK-----. Do not wrap in JSON or add quotes.
• Symmetric passphrase: Store the passphrase as a plain string with no JSON wrapper or quotes.

Use secret type Other type of secret with Plaintext format when creating the secret in AWS.

If the secret is stored with a JSON wrapper (e.g. {"key": "..."}) or surrounding quotes, the Decrypt Files node will reject it with an error asking you to re-store the value as raw text.

Step 2 — Create an AWS Secrets Manager account

An "account" represents the IAM role configuration that OneSchema uses to authenticate to your AWS account. You can create one via the dashboard or the API.

Option A — Dashboard

Navigate to Settings → Connections in the OneSchema dashboard, then select the AWS Secrets Manager tab.

Click Create AWS Secrets Manager connection. In the dialog, fill in:

Click Save Changes. The new connection appears in the table showing the Role ARN and whether an External ID is configured.

Option B — API

curl -X POST "https://api.oneschema.co/v0/aws-secrets-manager/accounts" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Decryption Keys",
    "role_arn": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/OneSchemaFileDecryptionKeysReader",
    "external_id": "<EXTERNAL_ID>"
  }'

Save the returned id — this is the account_id used when creating managed secrets and testing the connection.

Response:

{
  "id": 1,
  "name": "Production Decryption Keys",
  "role_arn": "arn:aws:iam::123456789012:role/OneSchemaFileDecryptionKeysReader",
  "has_external_id": true,
  "created_at": "2026-04-30T12:00:00Z",
  "updated_at": "2026-04-30T12:00:00Z"
}

The external_id value is never returned in API responses — only a has_external_id boolean.

Only Admin users can create, edit, or delete connections. Developer-role users can view connections and manage managed secrets.

Step 3 — Add managed secrets

Managed secrets are references to specific secrets in AWS Secrets Manager. They do not store the secret value in OneSchema — only the identifier needed to fetch it at runtime.

Option A — Dashboard

1. In the connections table, click the expand arrow (▶) next to your connection to reveal the Managed Secrets panel.

   

2. Click Add secret.

   

3. Fill in the following fields:

4. Click Create secret.

The managed secret now appears in the panel table with its identifier, region, and version information.

Option B — API

curl -X POST "https://api.oneschema.co/v0/aws-secrets-manager/accounts/1/secrets" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PGP Decryption Key - Vendor A",
    "secret_identifier": "prod/vendor-a/pgp-key",
    "region": "us-east-1"
  }'

Replace 1 in the URL with the account_id returned in Step 2.

Response:

{
  "id": 10,
  "name": "PGP Decryption Key - Vendor A",
  "account_id": 1,
  "secret_identifier": "prod/vendor-a/pgp-key",
  "region": "us-east-1",
  "secret_version": null,
  "version_kind": null,
  "created_at": "2026-04-30T12:00:00Z",
  "updated_at": "2026-04-30T12:00:00Z"
}

Step 4 — Test the connection

Before using the secret in a workflow, verify that OneSchema can successfully authenticate and retrieve it.

Option A — Dashboard

1. In the connections table, click the ⋮ (actions) menu on your connection row and select Test connection.

   

2. In the test dialog, select a managed secret from the dropdown and click Test.

   

   Look for a green success message.

Option B — API

curl -X POST "https://api.oneschema.co/v0/aws-secrets-manager/accounts/1/test" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_identifier": "prod/vendor-a/pgp-key",
    "region": "us-east-1"
  }'

A successful response:

{
  "success": true,
  "request_id": "abc-123",
  "transaction_id": "txn-456"
}

A failed response includes an error_category to help diagnose the issue:

{
  "success": false,
  "error_code": "AUTH_FAILED",
  "error_category": "account",
  "error_message": "Authentication failed",
  "request_id": "abc-123",
  "transaction_id": "txn-456"
}

Error reference

If successful, you will see a confirmation message. If the test fails, the dialog displays a categorized error:

Next steps

With your account and managed secrets configured, you can use them in the Decrypt Files node to decrypt GPG/PGP-encrypted files in your Multi FileFeed workflows.

Editing and deleting

• Edit an account: Click the ⋮ menu on the connection row and select Edit. You can update the name, description, Role ARN, and External ID. Existing managed secrets are preserved. Via the API: PATCH /v0/aws-secrets-manager/accounts/{id}.
• Edit a managed secret: Expand the connection's managed secrets panel, click the ⋮ menu on the secret row, and select Edit. Via the API: PATCH /v0/aws-secrets-manager/secrets/{id}.
• Delete: Connections and managed secrets can be deleted via their ⋮ menus. A connection cannot be deleted while it has managed secrets attached. Via the API: DELETE /v0/aws-secrets-manager/accounts/{id} or DELETE /v0/aws-secrets-manager/secrets/{id}.

See also the API documentation for /v0/aws-secrets-manager/accounts and /v0/aws-secrets-manager/secrets