--- title: Manage Agent credentials canonical: "https://agentbarn.dev/guides/integrations/credentials" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-05T09:17:18.000Z" author: Agent Barn description: "Add, replace, validate, attach, and remove encrypted Agent Secrets and Shared Credentials for Runtime tool Integrations." tags: [Integrations, Concept, "Agent operators, Organization administrators, and security reviewers", Agent credentials, Agent Secrets, tool credentials, Shared Credentials, credential rotation, credential validation, provider scopes, write-only secrets, agent.secret.manage] categories: [Guides, Integrations] --- - Integrations - 12–15 minutes Add, replace, validate, attach, and remove the encrypted credentials used by an Agent’s Runtime tool Integrations. This page covers per-Agent Agent Secrets, Organization-owned Shared Credentials attached to an Agent, and Runtime materialization for tool Integrations. Slack, Teams, Telegram, and Discord message-delivery credentials belong to Communication Connections and are managed separately. **Security rule** Credential values are write-only. Agent Barn never returns stored tokens, passwords, client secrets, refresh tokens, or other credential contents through read APIs. ## Before changing an Agent’s credentials You need access to the Agent and permission to update it and manage its credentials. The built-in Agent Editor and Agent Owner roles provide this access. Organization Owners and Admins also have authority over their Organization’s Agents. Organization membership or Agent Viewer access alone is not enough to change an existing Agent’s credentials. This requirement applies whether you enter a credential for that Agent or select an existing Shared Credential. If you are creating a new Agent, follow the hire flow’s credential steps instead. Selecting a credential during authorized Agent creation is a separate operation. See [Use shared credentials](/guides/integrations/shared-credentials) for the supported providers and the permissions needed to manage reusable credentials. You also need a least-privilege tool credential and the required Skill configuration. Tool credential updates for a running Agent use the explicit apply-and-restart workflow. This is separate from Communication Connection reconciliation. ## Understand the credential boundaries | Credential class | Owner | Used by | Managed from | Runtime materialized | | --- | --- | --- | --- | --- | | Agent Secret | One Agent | Runtime tool Integration | Keys & integrations | Yes | | Shared Credential | Organization | Attached Agent Runtime tool Integration | Shared Credentials, then Keys & integrations | Yes, when attached | | Deployment credential | Deployment/operator | Agent Barn infrastructure | Deployment configuration | No | | Communication Connection credential | One Agent-subordinate Connection | Communications service and Platform Plugin | Communication Connections | Never | **Important** Messaging credentials are Connection credentials. Manage them from the Agent’s [Communication Connections](/guides/agents/communication-connections) section. Platform Plugins validate and encrypt them, and the Communications service uses them without exposing them to Hermes or OpenClaw. ## Agent integration credentials An Agent Secret gives one Agent access to one external tool provider. For a provider, the Agent uses either a per-Agent Agent Secret or an eligible attached Shared Credential, never both simultaneously. Provider content is schema-validated before encryption and again after decryption. Complete provider payloads replace prior payloads; fields are not merged. ## Shared Credentials Shared Credentials are encrypted, Organization-owned tool credentials. Permitted Agents attach a reference rather than a second copy of the provider payload. Eligible Shared Credential providers are GitHub, Jira, Confluence, Bitbucket, and Zoho Mail. Google Workspace OAuth is not shareable. Deletion is protected while a non-deleted Agent references a Shared Credential. See [Use shared credentials](/guides/integrations/shared-credentials) for the Organization lifecycle. ## Slack tool access is an explicit Integration The provider ID is `slack`, and the UI labels it **Slack tool access**. It accepts a manually supplied Slack bot or user token, stores it as an Agent Secret, and may live-validate it. Runtime materialization creates the `slack-work` aai-cli profile. The tool workflow is read-oriented: channel data, files and attachments, bookmarks, links, and canvases. It is exposed only to the Agent’s Slack tool workflow or Skill; it does not receive messages for the Agent or configure a Communication Connection. **Important** A Slack tool credential and a Slack Communication Connection may use different tokens, scopes, and identities. Configuring either one does not create, update, or derive the other. ## Choose the correct credential boundary | Requirement | Use | | --- | --- | | One Agent needs tool access | Agent Secret | | Several Agents intentionally share one eligible manual tool credential | Shared Credential | | Google Workspace uses an individual OAuth grant | Per-Agent Agent Secret | | The Agent must receive or send Slack, Teams, Telegram, or Discord messages | Communication Connection | | All Agents use deployment Firecrawl | Platform Firecrawl configuration | | One Agent overrides Firecrawl | Per-Agent Firecrawl Agent Secret | | The Runtime needs Slack read-oriented tool access | Explicit Slack Agent Secret | ## Supported tool providers Google Workspace is the single Google provider. Zoho Calendar has a backend schema but is not currently offered in the web interface. | Provider | Method | Access boundary | Live validation | | --- | --- | --- | --- | | GitHub | Personal access token | Repositories and token scopes | Yes | | Jira / Confluence | Atlassian API token | Site, projects, and spaces | Yes | | Bitbucket | Email and API token | Workspace and repositories | Yes | | Google Workspace | OAuth | Selected services and access level | Yes | | Zoho Mail | OAuth client credentials | One Zoho Mail account | Not offered in the web interface | | Firecrawl | API key | Firecrawl Cloud or custom instance | Not offered in the web interface | | Pipedrive | Personal API token | Pipedrive account | Yes | | Slack | Manually supplied bot or user token | Workspace access and scopes granted to that token; Runtime tool access, not message transport | Yes | Live validation is separate from schema validation. Every saved payload must match its provider schema, but only providers with a validator can test access against the external service. ## Runtime activation Storage and Runtime activation are separate phases. ``` Enter tool credential │ ▼ Validate and encrypt │ ▼ Start or restart Agent │ ▼ Runtime materialization ├── aai-cli profile and secret store ├── gog Google Workspace setup ├── permitted environment └── eligible Skills and policy ``` Agent start may decrypt Agent Secrets or resolve attached Shared Credentials to build aai-cli configuration and its secret store, Google Workspace gog setup, permitted environment, exact assigned Skill versions and eligible bundled Skills, and tool Integration policy in rendered Agent instructions. Communication Connection credentials, provider sessions, access policies, and transport configuration do not participate in Runtime materialization. ## Open Keys & integrations 1. Open the Agent. 2. Go to **Configuration**. 3. Select **Keys & integrations**. 4. Review tool Integration credential metadata only. Manage messaging credentials in the relevant Communication Connection or provider setup guide; do not rotate them through Agent Secrets. ## Add or attach tool credentials 1. Select **Edit** in Keys & integrations. 2. Select a tool provider and enter its complete Agent Secret payload, or attach an eligible Shared Credential. 3. Review the provider scope guidance and apply the configuration. Skills that require a provider are satisfied only by a per-Agent Agent Secret or an eligible attached Shared Credential. Slack tool access requires an explicit Slack Agent Secret; a Slack Communication Connection is not provider coverage. ## Validate, replace, or remove Replace a credential with a complete payload, validate it where a provider validator is available, and remove it only after assigned Skill requirements remain satisfied. Agent Secret and attached Shared Credential changes require a start or restart before Runtime materialization changes. This does not apply to Communication Connection credential changes, which reconcile independently through the Communications supervisor. ## Google Workspace credentials One Google Workspace OAuth credential can cover selected Gmail, Calendar, Drive, and Sheets services. Its service choices, access level, granted scopes, and account identity are stored together and materialized through `gog`. Changing selected services or access level requires reconnecting Google Workspace so the correct scopes can be granted. ## Provider boundaries GitHub, Jira, and Confluence credentials inherit the access of their provider identity; restrict that identity to intended repositories, projects, and spaces. Deployment Firecrawl is available to all Agents when configured, while a per-Agent Firecrawl Secret overrides it for that Agent. ## Permission boundary Agent Secret changes require Agent access and `agent.secret.manage`. Attachment of Shared Credentials requires the appropriate Agent configuration access. Communication Connection settings require `agent.update`; creating, replacing, or retiring Connection credentials additionally requires `agent.secret.manage`. ## API reference Agent Secret update payloads sit under the active Organization API base path and never contain Connection credentials. ### Read metadata ``` { "secrets": [ { "provider": "github", "secret_name": "GitHub credential", "shared_credential_id": null }, { "provider": "jira", "secret_name": "Support Jira", "shared_credential_id": "3fd08cf5-59c5-494b-9449-a0413109a0ca" } ] } ``` ### Add an Agent Secret ``` { "secrets": [{ "provider": "github", "content": { "token": "REDACTED", "owner": "example-org", "org": "example-org", "repos": ["support-api"] } }] } ``` ### Attach a Shared Credential ``` { "shared_credentials": [{ "shared_credential_id": "3fd08cf5-59c5-494b-9449-a0413109a0ca" }] } ``` ### Remove credentials ``` { "removed_secret_providers": ["github", "jira"] } ``` ### Validate a credential `POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/{provider}/validate` ``` { "validation_status": "valid", "validation_identity": "example-org", "validation_error": null, "missing_scopes": [] } ``` ### Connection routes Manage messaging credentials with `POST /agents/{agent_id}/connections`, `PATCH /agents/{agent_id}/connections/{connection_id}`, and `DELETE /agents/{agent_id}/connections/{connection_id}` beneath the active Organization API base path. They are not Agent Secret update payloads. ## Troubleshooting ### I cannot see the existing token Expected: values are write-only Enter a complete replacement credential when rotation is required. ### I configured Slack messaging, but Slack tool access is unavailable Messaging does not create tool access A Slack Communication Connection does not create a Slack Agent Secret. Add a Slack tool credential in Keys & integrations and ensure the relevant Skill is assigned. ### A Shared Credential conflicts with a manual credential One source per provider Remove or replace the manual credential before attaching the Shared Credential. ### Provider messaging has failed Use Connection diagnostics Direct message-delivery token conflicts and provider-session failures to the affected Connection and [Communication diagnostics](/guides/observe-and-govern/communication-diagnostics). ### Removing a credential did not revoke the external token Revocation happens at the provider Agent Barn removes its stored access; revoke the token through the provider administration interface. ## Recommended practices - Prefer read-only access and restrict provider identities to intended resources. - Assign only required Skills and use Shared Credentials only when reuse is intentional. - Restart and test only after Agent Secret or Shared Credential changes; Connection changes reconcile independently. - Never place credentials in Templates, Skills, prompts, memory, or logs. - Restrict `agent.secret.manage` to trusted operators and revoke old external tokens after rotation. ## Next steps - [Connect Integrations and Credentials Safely](/guides/integrations-and-credentials) - [Use shared credentials](/guides/integrations/shared-credentials) - [Manage Communication Connections](/guides/agents/communication-connections) - [Browse Platforms](/guides/platforms) - [Use Communication diagnostics](/guides/observe-and-govern/communication-diagnostics)