Secrets and connector credentials
Connector credentials are stored in your Secrets Manager, reach a sandbox only for the duration of one execution, and never appear in a Lambda function's configuration, a table, a log line or a Library. This page covers where each secret lives, how it reaches code, how the AWS connector avoids storing any long-lived secret at all, and exactly what travels when a resource is shared between deployments.
Who this is for
Security engineers reviewing secret handling, and administrators deciding what may be shared through Libraries.
Before you start
Connectors are defined by users in Studio: SQL (PostgreSQL, MySQL), Snowflake, REST or OpenAPI, MCP and AWS. The user-facing pages are under Data connectors. Sharing is described for users in Libraries and sharing.
Where credentials live
| Store | Holds | Who reads it |
|---|---|---|
alphaagent-data-connectors (DynamoDB) | The connector's non-secret definition: type, name, host, database, auth type, versions, the count of secret headers | The data-connector service |
alphaagent-data-connector-secrets (Secrets Manager) | One JSON body with an entry per connector id: the credential (password, token, key pair, role and External ID) and any request headers you marked as secret | The data-connector and code-interpreter services, through the Studio task role |
alphaagent-connector-creds-<agent id> (Secrets Manager) | The credentials of exactly the connectors assigned to one agent, written when the agent is configured | The sandbox, through the scoped session for that agent only |
The Studio task role may read secrets named alphaagent-*; the sandbox scoped role may read only alphaagent-connector-creds-*, and each session is narrowed to the one secret for the invoking agent. See Sandbox isolation.
How a credential reaches running code
At the start of an execution the sandbox handler fetches the agent's connector secret and flattens each connector into environment variables for the child process only, named CONN_<connector id>_<KEY>. A SQL connector surfaces host, database and credentials; an MCP connector surfaces the server URL and headers; a Snowflake connector surfaces the account, user, role, warehouse, database, schema and either the access token or the private key and passphrase. The handler's own process environment is never changed, so nothing is left for the next invocation, and the function's configuration never carries a value.
Shell commands run under bash: connector ids contain hyphens, and /bin/sh would drop those variables before the command runs.
A credential is only issued for an agent that is actually assigned the connector. The per-agent secret is written from the agent's configuration, and the session policy prevents a sandbox from reading any other agent's secret.
The AWS connector: a role you own
An AWS connector holds no long-lived key. You create an IAM role in your own account whose trust policy allows the deployment's task role to assume it, on the condition that sts:ExternalId equals a value Studio generated for that connector. Studio then:
- Reads the role's trust policy when you save or test the connector and refuses a role whose trust does not actually enforce the External ID condition, so a successful test proves the anti-confused-deputy check is in place, not just that a call succeeded.
- At run time, calls
sts:AssumeRoleand hands the sandbox the resulting temporary credentials. They expire on their own, and what the code can do is exactly what your policy on that role allows.
Secret headers on REST connectors
A REST or OpenAPI connector can carry request headers. Headers you mark as secret (for example an Authorization or API-key header) are stored in the credential secret, not in the table; the table keeps only their count. In a Library, the item shows auth_type, header_count and whether an OpenAPI specification is attached, never a header value.
What sharing relays
Sharing has two halves, and they are deliberately different.
Push catalogues. When a user shares a resource, Studio writes a request row in its own account. The Organisations engine, which already polls every registered account, picks it up, re-derives from its own membership rows that the requester is a Contributor on that Library, and catalogues an item: a pointer to the source version plus display fields. Nothing read from the request row is treated as authorisation, and no credential, graph content or table data is ever written to a Library.
Pull relays. When a user downloads an item or updates their copy, the engine opens two sessions, one into the source deployment's account and one into the target's, reads the source live, and writes the target. What travels per type:
| Type | Catalogued in the Library | Relayed on pull | Sensitive material |
|---|---|---|---|
| Agent | Agent id, version, name, type, description, and its dependencies (connectors, environment, knowledge graph, versions) | The pinned agent version, re-read live; a new agent row in the target with re-wired pins when pulled as part of a bundle | None on an agent row |
| Workflow | Per node, the agent's pinned version and that version's pins; a pull-ordered dependency list | Each dependency through its own adapter, then the graph with re-mapped agent ids; lands as a draft to activate | Follows each dependency |
| Connector | Id, version, type, name, endpoint host, auth type, status, header count, whether a specification is attached | The definition re-read live with credential fields stripped, then the credential itself: read from the source account's credential secret and written into the target account's credential secret under the new connector id, in the engine's memory for the duration of one relay call. Never stored in the Library, never staged to S3, never logged | The credential moves account to account. The copy is marked as needing attention when the source credential is gone or secret headers could not be copied |
| AWS connector | As above | The role ARN and External ID move with the credential. The Studio share notice tells the sharer that the recipient's account must be added to the role's trust policy, and the recipient sees the exact account id to add | Your role's trust policy decides who may assume it |
| Environment | The row and image reference | A custom image is copied by digest from the source account's repository into the target's; built-in images carry their name | Registry tokens per account, nothing else |
| Knowledge graph | A pointer to the version plus node and edge counts | A one-shot task in the source exports the version to the source staging bucket; the engine copies it to the target staging bucket; a task in the target imports it as a new version | Neo4j credentials come from each deployment's own configuration secret |
Every pulled copy records where it came from: Library, item, version, source deployment, who pushed and who pulled, and when.
Steps: verify secret handling in your account
- In Secrets Manager, filter by
alphaagent-. You should see the configuration shells,alphaagent-data-connector-secrets, and onealphaagent-connector-creds-<agent id>per configured agent. - Open any
alphaagent-env-*Lambda function. NoCONN_variable in its configuration. - For an AWS connector, open the role you created. The trust policy carries
Condition: StringEquals sts:ExternalId, and the principal is the deployment's task role. - In the Organisations console, open a Library that holds a connector and read its item. Endpoint host and auth type are shown; no credential value is.
What you should see
- Secret reads in CloudTrail from the sandbox scoped role name only
alphaagent-connector-creds-*. - The Library item for a connector changes when the sharer pushes a new version and never carries a value from the credential secret.
Limits
- One credential secret per deployment holds every connector's credential; access is by IAM role, not per connector. Per-agent secrets are the narrower unit the sandbox sees.
- A pulled AWS connector cannot connect until the recipient's account is trusted by your role.
- Secret headers on a REST connector are classified by you when you create the connector; a header left unclassified is stored as a plain field.
If something goes wrong
- A pulled connector shows "needs attention": the source credential was removed before the pull, or a secret header could not be copied. Re-enter the credential in the target.
- A test of an AWS connector fails naming the External ID: the trust policy is missing the condition. Add it and test again.
- A service control policy that denies Secrets Manager stops both the install and every execution; see SCPs and guardrails.