Manage Agent credentials

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 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

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 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.

Choose the correct credential boundary

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.

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.

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

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
• Use shared credentials
• Manage Communication Connections
• Browse Platforms
• Use Communication diagnostics