How to Setup AWS Assume Role for AWS Secret Manager

Updated:


March 12, 2026

This guide walks you through configuring AWS IAM Assume Role so that Unified can securely access AWS Secrets Manager in your account — without sharing long-lived AWS access keys.

Overview

Instead of providing static AWS credentials (access key + secret), you can create an IAM role in your AWS account and grant Unified permission to assume it. Unified uses AWS STS (Security Token Service) to obtain short-lived, temporary credentials scoped to your Secrets Manager.

How it works

┌───────────────┐         STS AssumeRole          ┌────────────────────┐
│  Unified API  │ ──────────────────────────────► │  Your AWS Account  │
│  (account     │   (with External ID check)      │                    │
│   944579081756│ ◄────────────────────────────── │  IAM Role          │
└───────────────┘    temporary credentials        │  Secrets Manager   │
                                                  └────────────────────┘
  1. You create an IAM role in your AWS account with a trust policy that allows Unified's AWS account to assume it.
  2. You attach a permissions policy to that role granting access to Secrets Manager.
  3. You provide the role's ARN and an External ID in the Unified dashboard.
  4. Unified calls sts:AssumeRole with the External ID, receives temporary credentials, and uses them to read/write secrets.

Prerequisites

  • An AWS account with permissions to create IAM roles and policies
  • Access to the Unified dashboard with workspace admin permissions

Step 1: Create an IAM Policy for Secrets Manager

In the AWS Console, create a policy that grants the permissions Unified needs on Secrets Manager.

  1. Go to IAM > Policies > Create policy
  2. Select the JSON tab and paste the following:
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "secretsmanager:CreateSecret",
                    "secretsmanager:GetSecretValue",
                    "secretsmanager:UpdateSecret",
                    "secretsmanager:DeleteSecret"
                ],
                "Resource": "arn:aws:secretsmanager:YOUR_REGION:YOUR_ACCOUNT_ID:secret:*"
            }
        ]
    }
    

    Replace YOUR_REGION (e.g. us-east-1) and YOUR_ACCOUNT_ID with your values.
    Tip: To restrict access further, you can narrow the Resource to a specific prefix, for example: arn:aws:secretsmanager:us-east-1:123456789012:secret:unified/*
  3. Name the policy (e.g. UnifiedSecretsManagerAccess) and create it.

Step 2: Create an IAM Role with a Trust Policy

  1. Go to IAM > Roles > Create role
  2. Select Custom trust policy and paste the following:
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::944579081756:user/unified_assume_role_user"
                },
                "Action": "sts:AssumeRole",
                "Condition": {
                    "StringEquals": {
                        "sts:ExternalId": "YOUR_EXTERNAL_ID"
                    }
                }
            }
        ]
    }
    

    Replace YOUR_EXTERNAL_ID with a unique, hard-to-guess string of your choice (e.g. a UUID). You will enter this same value in the Unified dashboard later.
    Why an External ID? The External ID prevents the confused deputy problem. It ensures that only requests originating through your Unified workspace — and not a third party who happens to know the role ARN — can assume the role.
  3. Click Next, then attach the UnifiedSecretsManagerAccess policy you created in Step 1.
  4. Name the role (e.g. UnifiedSecretsManagerRole) and create it.
  5. Copy the role's ARN from the role summary page. It will look like: arn:aws:iam::123456789012:role/UnifiedSecretsManagerRole

Step 3: Configure Unified

  1. Log in to the Unified dashboard.
  2. Navigate to Settings > Workspace Settings.
  3. Under the secrets manager section, select AWS Secret Manager.
  4. Fill in the following fields:
    FieldValue
    AWS RegionThe region where your Secrets Manager secrets are stored (e.g. us-east-1)
    AWS ARNThe full ARN of the IAM role you created (e.g. arn:aws:iam::123456789012:role/UnifiedSecretsManagerRole)
    AWS External IDThe same External ID string you used in the trust policy
    Note: When using Assume Role, you do not need to fill in the AWS Key and AWS Secret fields. Those fields are only required for the static-credentials approach.
  5. Save your workspace settings.

Step 4: Verify the Setup

Once saved, Unified will automatically use the Assume Role flow for all new connections in your workspace. To verify:

  1. Create or update a connection in your workspace.
  2. Check your AWS Secrets Manager console — you should see a new secret created with a name that includes your workspace ID.
  3. If there are any issues, Unified will surface errors in the connection status.

Troubleshooting

'Missing role ARN or region'

Ensure both the AWS Region and AWS ARN fields are filled in on your workspace settings.

'Access Denied' or 'Not authorized to perform sts:AssumeRole'

  • Verify the trust policy on your IAM role references the correct Unified AWS principal: arn:aws:iam::944579081756:user/unified_assume_role_user
  • Verify the External ID in the trust policy matches exactly what you entered in Unified.
  • Ensure the IAM role's permissions policy includes the required secretsmanager:* actions.

'The security token included in the request is expired'

Temporary credentials are cached for up to 55 minutes and refreshed automatically. If you see this error persistently, confirm that your IAM role allows a session duration of at least 1 hour (the default).

Secrets are not being stored

  • Confirm the IAM role's permissions policy allows actions on the correct region and account.
  • Check that the Resource in your permissions policy matches the region configured in Unified.

Migrating from Static Credentials

If you are currently using the static AWS Key / AWS Secret approach:

  1. Follow Steps 1-3 above to set up the IAM role and configure Unified.
  2. Once the ARN and External ID are saved, Unified will prefer the Assume Role flow over static credentials.
  3. After verifying that secrets are being read and written correctly, you can remove the static AWS Key and AWS Secret from your workspace settings.
  4. Revoke or delete the old IAM user credentials in your AWS account.

Security Best Practices

  • Use a unique External ID per workspace. This prevents cross-workspace role assumption.
  • Scope the permissions policy narrowly. Restrict the Resource to only the secret prefixes Unified needs.
  • Rotate the External ID periodically. Update both the IAM trust policy and the Unified dashboard when you do.
  • Enable CloudTrail logging. Monitor AssumeRole events in your AWS account to audit access.
  • Do not share the External ID publicly. Treat it as a sensitive configuration value.
Share
All guidesAccounting Account Type Hierarchy in UnifiedAdvertising Report Metrics by IntegrationAmazon S3: Required IAM PermissionsATS to Vector DB: How to Power Talent Intelligence with Real-Time DataBuilding AI applications with Unified and LangbaseConcur & Concur (Company) — Connection GuideConfigure Greenhouse Native Candidate WebhooksConfigure Salesforce Meetings and Notes for UnifiedConnect Amazon Seller Central to Unified.toConnecting BambooHR via OAuth 2Connecting Google Workspace Integrations with a Service AccountCorrect WelcomeKit Scopes for Jungle IntegrationCreating Ads using the Unified Ads APICreating Walmart Items via UnifiedEnd-Users, Integrations, and ConnectionsEnriching Unified Objects with Custom MetadataEnterprise-managed authorization (EMA) with a static keyEnterprise-managed authorization (EMA) with a workspace secretEnterprise-managed authorization (EMA) with Microsoft Entra IDExtended observability — pushing API logs to ClickHouseExtended observability — pushing API logs to Grafana / LokiExtended Observability - Pushing API Logs to your Datadog InstanceFacebook Messenger Webhook SetupFireflies Integration GuideGetting started with WorkableHandling Delegated vs. Application Scopes in Microsoft IntegrationsHiBob & Unified: connection and time off guideHow long are logs retainedHow to access employees and usersHow to add API support for the Create Activity in CrelateHow to Associate a Connection ID with Your End-UserHow to build a Candidate Assessment product withHow to build a candidate sourcing or job board app with Unified.toHow to build a Discord support bot with Unified.to and LangbaseHow to Build a Fintech Application with Unified's Payments APIHow to Build an E-Commerce Product Integration with UnifiedHow to build an invoicing system with Unified.toHow to build Enterprise Search using RAGHow to configure Bullhorn Redirect URI for creating a connectionHow to configure webhooks in HubSpotHow to configure webhooks in Thrive LearningHow to configure webhooks in Toast for UnifiedHow to Connect Anthropic to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Cohere to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Google Gemini to Real-Time SaaS Data with Unified.to MCP ServerHow to connect HiBob (Bob) to Unified with OAuth 2.0How to Connect LLMs to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect OpenAI to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Zoom and Zoom PhoneHow to create a Connection In Microsoft TeamsHow to create a token-based connection in HighlevelHow to Create a Unified.to Connection to HighLevelHow to Create a Xero Connection in Unified.toHow to create and configure webhooksHow to create Connection with HubspotHow to customize portal URLs for Stripe and GoCardlessHow to filter webhook eventsHow-to Get a Private Support Channel for Your Unified IntegrationHow to get help fromHow to get your 8x8 Connect API Key, Account ID and SMS Subaccount ID (optional): Step-by-step guideHow to get your ADP Workforce Now Oauth2 client ID, Oauth2 client secret, Oauth2 PEM certificate and Oauth2 private key: Step-by-step guideHow to get your Amazon S3 AWS Region, AWS S3 Key, AWS S3 Secret and AWS S3 Bucket(s) (optional, comma-separated): Step-by-step guideHow to get your Ashby API Key: Step-by-step guideHow to get your Brex API token: Step-by-step guideHow to get your Bullhorn OAuth2 Client ID, OAuth2 Client Secret, API Username and API Password: Step-by-step guideHow to get your Ceridian Dayforce Username, Password and Client Namespace: Step-by-step guideHow to get your Crelate API key: Step-by-step guideHow to get your Dashlane API Key: Step-by-step guideHow to get your Deel Access Token: Step-by-step guideHow to get your Dialpad API Key: Step-by-step guideHow to get your Discord OAuth 2 credentials and bot tokenHow to get your ELMO client ID and client secret: Step-by-step guideHow to get your Gainsight Client ID, Client Secret and Gainsight API Domain: Step-by-step guideHow to get your Greenhouse API Key and Job board token: Step-by-step guideHow to get your Helpscout API Key: Step-by-step guideHow to get your HiBob Service User ID and Service User Token: Step-by-step guideHow to get your HighLevel API Key and Location ID: Step-by-step guideHow to get your HubSpot developer key and OAuth 2 credentials (Legacy Apps)How to get your Humaans API Key: Step-by-step guideHow to get your iCIMS API Username, API Password and Customer ID: Step-by-step guideHow to get your JobDiva Client ID, Username/email and Password: Step-by-step guideHow to get your Jobvite API Key, API Key Secret and Email: Step-by-step guideHow to get your Lever API Key: Step-by-step guideHow to get your Loxo Agency slug, API Key and Agency ID: Step-by-step guideHow to get your Microsoft Active Directory / Entra ID Client ID, Client Secret and Tenant ID: Step-by-step guideHow to get your Microsoft Azure AD OAuth 2 credentialsHow to get your OAuth 2 credentials for GmailHow to get your OAuth 2 credentials for Microsoft Dynamics 365How to get your OAuth 2 credentials in PipeDriveHow to get your OpenAI API Key: Step-by-step guideHow to get your Paycom SID/Username and Token/Password: Step-by-step guideHow to get your PCRecruiter Username, Password, Database ID, App Key and App ID: Step-by-step guideHow to get your SAP SuccessFactors (OpenID Connect) Username, Password, Client ID, Client Secret, Dependency Name, IAS Host and API URL: Step-by-step guideHow to get your SAP SuccessFactors Username, Company ID, Password and API URL: Step-by-step guideHow to get your Shopify Admin API access token and Store ID: Step-by-step guideHow to get your Wayfair Client ID, Client Secret and Vendor Encrypted Key: Step-by-step guideHow to get your Workable API Token and Subdomain: Step-by-step guideHow to get your yotpo APP Key / Store ID and Secret Key: Step-by-step guideHow to Handle Attachments in Invoice, Bill and Credit MemoHow to Manage Google Ad Manager Orders, Line Items and Creatives with theHow to migrate or import your integrations into Unified.toHow to obtain your GitHub OAuth2 credentialsHow to Power Claude with Live Customer Data Using Unified MCPHow to receive assessment orders from an ATS with Unified.toHow to register a Google developer app and get OAuth 2 credentialsHow to Register a HiBob Developer App and Get OAUTH2 CredentialsHow to register a Salesforce developer app and get OAuth 2 credentialsHow to register a Slack developer account and get OAuth 2 credentialsHow to Register a Workday Developer App and Get OAUTH2 CredentialsHow to Register a Workday Developer App and Get OAUTH2/ SOAP CredentialsHow to Register a ZendeskSell Developer App and Get OAUTH2 CredentialsHow to Register a Zoho Developer App and Get OAUTH2 CredentialsHow to Register an ADP Developer App and Get OAUTH2 CredentialsHow to Register an Atlassian Developer App and Get OAUTH2 CredentialsHow to Register your Facebook OAuth2 ApplicationHow to Register your Google Ads OAuth2 ApplicationHow to Register your MetaAds OAuth2 applicationHow To Request & Write Raw Integration DataHow to Retrieve Microsoft Dynamics 365 Business Central CredentialsHow to set up a custom API URL with a CNAMEHow to Set Up a Google Meet Meeting Bot with UnifiedHow to set up a HiBob marketplace installHow to Set Up a Microsoft Teams Bot with UnifiedHow to Set Up a Microsoft Teams Meeting Bot with UnifiedHow to Set Up a Webex Meeting Bot with UnifiedHow to Set Up a Zoom Meeting Bot with UnifiedHow to set up and configure NotionHow to set up Google Business Profile API access and get OAuth 2 credentialsHow to Set Up LinkedIn Webhooks with UnifiedHow to set up native webhooks for QuickBooks Online with UnifiedHow to set up Slack webhooks using event subscriptionsHow to set up Telegram (bot) with Unified.toHow to set up your scopes in HubSpotHow to setup a Freshbooks developer appHow to setup a TikTok Shop applicationHow to setup Oracle JD EdwardsHow to Setup Quickbooks DesktopHow to setup Sage 100 with Unified.toHow to test webhooks in the Synthetic Data (Sandbox) environmentHow to troubleshoot unhealthy connectionsHow to troubleshoot unhealthy webhooksHow to Use Decision Models with the Unified GenAI APIHow to use SCIM with the Unified APIHow to use the Passthrough APIHow to Use Unified.to's Generative AI API with OpenAI and ClaudeHow to use User Provisioning and Verification with UnifiedHow virtual webhook retry and recovery worksIntegration set-up guide for LeverManaging custom validation rules in SalesforceNetSuite Authentication Setup for UnifiedNotice of Deprecation of Fields and Objects (Nov 2025)Oracle HCM / Taleo OAuth Credentials GuideRetrieval-Augmented Generation (RAG)SalesForce (External Client Apps) on Multiple OrganizationsSAML Single-Sign-OnScaling MCP Tools with Anthropic's (& OpenAI's) Defer LoadingScaling MCP Tools with Anthropic's Programmatic Tool CallingSet Environments for your Unified.to WorkspaceSetting up a Slack Bot Connection with Unified.toSetting up OAuth 2 Credentials for Greenhouse's APIsTrello Connection Guide in UnifiedUnderstanding OAuth2 Authorization flowsUnderstanding Response Time Headers in the Unified APIUnified Assessment API: Embed Assessments Inside ATS PlatformsUnified's MCP ServerUnified MCP Server with LangChain and LangGraphUnlock real-time data with virtual webhooksUse Unified to sign in your users into your applicationVincere OAuth Setup Guide for UnifiedWhy you can't use Unified's OAuth2 credentials to authorize your end users on ProductionWorkable: Creating candidates and attaching them to jobsWorkday vs Workday Legacy — Why Unified.to Supports BothWorking with hierarchical tree data in Storage, Messaging, and KMS APIs
Are we missing anything? Let us know
Was this page helpful?