Manage Agent credentials

Before you begin

You need:

• Access to the Agent
• agent.update permission to update its configuration
• agent.secret.manage permission to add, replace, validate, or remove credentials
• Lifecycle permission when applying changes to a running Agent
• A credential with the least privileges required for the Agent’s work

The raw Agent update API accepts configuration changes only while the Agent is stopped. The web interface uses an explicit restart workflow when credentials are changed on a running Agent.

Understand the credential boundaries

Agent Barn has several credential classes with different owners and lifecycles.

Platform credentials

A Platform credential connects the Agent to its selected communication platform.

These credentials are separate from normal provider integration credentials. A Slack bot token lets the Agent connect to Slack as its communication channel; it is not a manually managed Slack integration Secret.

When a Slack Skill requires Slack access, Agent Barn derives and maintains the corresponding internal integration Secret from the Agent’s Slack bot token.

Slack and Discord bot tokens must be unique across active Agents. Agent Barn rejects a token that is already assigned to another active Agent.

Agent integration credentials

An Agent integration credential, also called an Agent Secret, gives one Agent access to one external provider. An Agent can have at most one credential for each provider.

Agent
├── GitHub credential
├── Jira credential
├── Google Workspace credential
└── Pipedrive credential

For a given provider, the Agent uses either a manually entered per-Agent credential, or a reference to an Organization Shared Credential. It cannot use both simultaneously.

Credential contents are validated against a provider-specific schema before encryption, and again after decryption.

Shared Credentials

Shared Credentials are encrypted provider credentials owned by an organization. They let administrators create a credential once, and allow organization members to attach it to permitted Agents.

Organization Shared Credential
Production GitHub
        │
        ├── Agent A
        ├── Agent B
        └── Agent C

Supported Shared Credential providers are GitHub, Jira, Confluence, Bitbucket, and Zoho Mail.

Any organization member can list and attach available Shared Credentials to Agents they are permitted to configure. Organization Owners and Administrators manage the shared definitions.

See Use shared credentials for the complete lifecycle.

Choose the correct credential boundary

Use separate provider accounts when Agents need different access boundaries.

Supported integration providers

Live validation support is separate from schema validation. Every saved payload must match its provider schema, but only providers with a validator can test the credential against the external service.

How credentials reach the Agent

Credential storage and runtime activation are separate phases.

1. Stored encrypted credential
2. Agent start
3. Runtime configuration
4. External provider

Enter credential
       │
       ▼
Validate payload shape
       │
       ▼
Encrypt and store
       │
       ▼
Start or restart Agent
       │
       ▼
Decrypt for runtime materialization
       │
       ├── aai-cli profile and secret store
       ├── gog Google Workspace configuration
       ├── runtime environment
       └── integration policy context
       │
       ▼
External provider

The encrypted database value is the source of truth. Agent Barn decrypts credentials only when required for validation or runtime materialization.

Read APIs return metadata such as the provider, the display label, whether the credential is Shared, and the Shared Credential name and ID where applicable. They do not return the credential content.

Runtime activation

Credential changes take effect in the Agent runtime after a start or restart.

Save credential
      │
      ▼
Credential stored
      │
      ▼
Start Agent
      │
      ▼
Runtime receives new configuration

Apply credential change
      │
      ▼
Stop Agent
      │
      ▼
Update encrypted configuration
      │
      ▼
Start Agent

Google Workspace credentials

Google Workspace uses a separate OAuth flow and the gog CLI. One credential can cover Gmail, Calendar, Drive, and Sheets.

The credential records the Google account email, the selected services, the granted scopes, the refresh token, the read-only or full-access selection, and the OAuth client information.

Changing the selected services or access level requires reconnecting, so Google can grant the correct scopes.

Google Workspace is per-Agent and cannot be attached as a Shared Credential. Continue to Connect Google Workspace for the full setup.

GitHub repository boundaries

A GitHub credential contains a token, an owner or organization, and an optional repository list.

Leaving the repository list empty allows the Agent to address any repository the token itself can access, provided the Agent specifies the repository.

For tighter control:

1. Use a fine-grained token.
2. Limit it to required repositories.
3. Grant only necessary permissions.
4. Repeat the repository restriction in Agent Barn.
5. Validate and test the intended repository.

The provider’s token permissions remain the ultimate authorization boundary.

Jira and Confluence boundaries

Jira and Confluence credentials inherit the permissions of the Atlassian account associated with the API token.

Agent Barn stores the site URL, the authentication type, the account email, the API token, and the resolved Cloud ID for scoped tokens.

Use an account limited to the intended projects or spaces. Selecting a site URL in Agent Barn does not reduce broader permissions already granted to the Atlassian account.

Firecrawl credentials

Firecrawl can be provided by the Agent Barn deployment. When the platform Firecrawl URL and API key are configured, Agents receive the platform web-fetch and search capability by default.

A per-Agent Firecrawl credential overrides the platform key for that Agent. Use a per-Agent override when:

• The Agent must use Firecrawl Cloud
• The Agent must use another Firecrawl instance
• Separate usage or billing boundaries are required
• The platform credential must not be used

Credential security model

Agent integration credential payloads are:

• Validated against provider-specific schemas
• Serialized as structured JSON
• Encrypted as a single Fernet-encrypted blob
• Revalidated after decryption
• Hidden from read responses
• Materialized only for runtime or validation use

Agent Barn enforces one Agent Secret per provider at the database level. A credential row contains either encrypted per-Agent content, or a Shared Credential reference — never both.

Credential-related event payloads and diagnostic metadata must not contain secret contents.

Permission boundary

Agent credential access follows the Agent access model.

API reference

Read credential metadata

GET /api/v1/organizations/{organization_id}/agents/{agent_id}

{
  "secrets": [
    {
      "provider": "github",
      "secret_name": "GitHub credential",
      "shared_credential_id": null,
      "shared_credential_name": null
    },
    {
      "provider": "jira",
      "secret_name": "Support Jira",
      "shared_credential_id": "3fd08cf5-59c5-494b-9449-a0413109a0ca",
      "shared_credential_name": "Support Jira"
    }
  ]
}

No content field is returned.

Add or replace a manual credential

The Agent must be stopped.

PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json

{
  "secrets": [
    {
      "provider": "github",
      "content": {
        "token": "REDACTED",
        "owner": "example-org",
        "org": "example-org",
        "repos": [
          "support-api",
          "support-web"
        ]
      }
    }
  ]
}

Providers not included in secrets remain unchanged. Every credential value in these examples is redacted — supply your own.

Attach a Shared Credential

{
  "shared_credentials": [
    {
      "shared_credential_id": "3fd08cf5-59c5-494b-9449-a0413109a0ca"
    }
  ]
}

The Shared Credential must belong to the Agent’s organization.

Remove credentials

{
  "removed_secret_providers": [
    "github",
    "jira"
  ]
}

A provider cannot appear in both secrets and removed_secret_providers in the same request.

Replace Platform credentials

For a stopped Slack Agent:

{
  "slack_bot_token": "REDACTED",
  "slack_app_token": "REDACTED"
}

Only submit platform fields that belong to the Agent’s selected platform.

Validate an integration

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/{provider}/validate

Example:

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/github/validate

{
  "validation_status": "valid",
  "validation_identity": "example-org",
  "validation_error": null,
  "missing_scopes": []
}

Validation requires agent.secret.manage.

Troubleshooting

Recommended practices

• Use a dedicated identity for each production Agent
• Grant the minimum provider scopes required
• Prefer read-only access when writes are unnecessary
• Limit credentials to intended repositories, projects, spaces, or services
• Use Shared Credentials only when Agents should truly share one identity
• Keep OAuth credentials per Agent
• Rotate credentials on a documented schedule
• Validate credentials after creation and rotation
• Restart and test the Agent after every credential change
• Revoke old tokens after confirming the replacement works
• Remove unused credentials promptly
• Never place credentials in Templates, Skills, prompts, memory, or logs
• Restrict agent.secret.manage to trusted operators
• Review Agent access before granting secret-management permission
• Investigate validation warnings and missing scopes rather than granting broad access

Next steps

Continue to Connect Google Workspace to configure a per-Agent OAuth credential for Gmail, Calendar, Drive, and Sheets.

• Use shared credentials
• Work with Skills
• Configure an Agent
• Share access to an Agent