Use shared credentials

What is a Shared Credential?

A Shared Credential is an encrypted, provider-specific credential owned by one Organization. Instead of storing another copy of the provider token on each Agent, Agent Barn stores a reference from the Agent to the Shared Credential.

The diagram shows a single Organization-owned credential named Production GitHub. Agent A, Agent B, and Agent C each store a reference to that one encrypted credential. The credential content is not copied into any of the three Agents.

When an Agent starts, Agent Barn follows the reference, decrypts the credential, and materializes the provider configuration the Agent runtime needs.

Credential plaintext is never returned through Shared Credential read APIs. Members can see metadata such as the name, the provider, and the number of attached Agents — but never the stored token or password.

When to use one

Supported providers

Shared Credentials currently support manual-entry credentials for these providers:

You can create multiple credentials for one provider. For example:

Production GitHub
Staging GitHub
Read-only GitHub
Finance Jira
Engineering Jira

Shared Credential names must be unique across the entire Organization, even when the credentials use different providers.

Roles and permissions

Shared Credential management and Agent attachment use different authorization boundaries. The Scope column names which boundary each action is checked against.

Attaching a Shared Credential to an Agent is not an Organization action alone. It also requires permission to update that Agent and to manage its secrets: agent.update and agent.secret.manage.

Organization Owners and Administrators hold implicit Agent Owner authority over Agents in their Organization. An Organization Member normally needs Agent Editor, Agent Owner, or a custom access role that grants both required permissions. An Agent Viewer cannot attach, replace, or remove credentials.

Before you begin

Review the provider-specific guide before creating the credential:

• Connect GitHub
• Connect Jira
• Connect Confluence
• Connect Bitbucket
• Connect Zoho

Replace an Agent credential

An Agent can have at most one credential source for each provider.

• Allowed A manual Agent credential for the provider
• Allowed A Shared Credential reference for the provider
• Not allowed A manual credential and a Shared Credential for the same provider

Switch from a manual credential to a Shared Credential

1. Stop the Agent.
2. Open the provider configuration.
3. Select Use shared credential.
4. Choose the Shared Credential.
5. Save the Agent.
6. Start the Agent and verify it.

The manual credential must be removed as part of the switch.

Switch between Shared Credentials

1. Stop the Agent.
2. Open the provider configuration.
3. Select the replacement Shared Credential.
4. Save the Agent and restart it.
5. Verify the new provider identity and access boundary.

The Agent keeps one provider slot and changes which Shared Credential it references.

Switch to a manual credential

1. Stop the Agent.
2. Select Enter credentials.
3. Complete all provider fields.
4. Save the Agent and restart it.
5. Verify the new credential.
6. Revoke the former provider credential only if no other Agent still uses it.

Verify the connection

Organization Owners and Administrators can open a Shared Credential and select Validate. Live validation is available for GitHub, Jira, Confluence, and Bitbucket.

Zoho Mail currently returns an unsupported live-validation result:

{
  "validation_status": "unsupported",
  "validation_identity": null,
  "validation_error": "Live validation is not available for this provider",
  "missing_scopes": []
}

For every provider, the authoritative end-to-end check is still a task performed by a restarted Agent. Live validation does not prove that the Agent’s selected resources, repository defaults, Skills, or runtime configuration are correct.

Rotate a Shared Credential

Updating one Shared Credential changes the stored source used by every attached Agent. It does not automatically restart those Agents.

1. Identify affected Agents Open the Shared Credential and review its Used by count. Record the Agents that reference it before you begin. The metadata reports a count; credential plaintext stays hidden.
2. Create the replacement provider key Create a new token or refresh token at the provider and grant only the required permissions. Keep the previous credential active during the rollout.
3. Update the Shared Credential Open the credential, select Edit credential, and enter the complete replacement payload.
4. Restart attached Agents Stop and start each affected Agent so its runtime receives the updated credential. Agents that keep running continue to use the configuration materialized at their previous start.
5. Verify each authorization boundary Run a small provider task from every affected Agent. Test permitted and prohibited resources where practical.
6. Revoke the previous provider key Revoke the old key only after all affected Agents have restarted and passed verification.

Detach or delete a credential

Detach it from an Agent

1. Stop the Agent.
2. Open its provider configuration.
3. Remove the provider, or switch to another credential source.
4. Save the Agent.
5. Restart the Agent and verify it.

If an assigned Skill requires the provider, Agent Barn may block the removal. Provider-dependent Skill requirements must remain satisfied, so replace the provider credential or remove the dependent Skill as part of a valid configuration change.

Delete it from the Organization

A Shared Credential cannot be deleted while any non-deleted Agent references it. To delete it:

1. Review the attached Agent count.
2. Detach or replace the credential on every affected Agent.
3. Return to Organization settings → Shared Credentials.
4. Open the credential.
5. Select Delete.
6. Confirm the deletion.

If an Agent still references the credential, Agent Barn returns a conflict similar to:

Shared credential is attached to 3 agent(s). Detach it from all agents before deleting.

Runtime behavior

At Agent start, Agent Barn:

1. Loads the Agent’s provider slots.
2. Identifies the slots that reference Shared Credentials.
3. Confirms each credential belongs to the Agent’s Organization.
4. Decrypts the provider-specific content.
5. Revalidates its schema.
6. Builds the runtime profile and secret-store configuration.
7. Mounts eligible built-in provider Skills.
8. Adds the integration policy to the rendered Agent configuration.

The runtime receives the provider content, not the Shared Credential management API.

Updating a Shared Credential therefore affects future Agent starts. It does not dynamically replace secrets inside an Agent that is already running.

API reference

List Shared Credentials

GET /api/v1/organizations/{organization_id}/shared-credentials?page=1&page_size=15

Optional filters:

search=Production
provider=github

The response includes metadata and agent_count, but never content.

List attachment options

GET /api/v1/organizations/{organization_id}/shared-credentials/briefs

[
  {
    "id": "018f0000-0000-7000-8000-000000000001",
    "provider": "github",
    "name": "Production GitHub"
  }
]

Create a Shared Credential

POST /api/v1/organizations/{organization_id}/shared-credentials
Content-Type: application/json

{
  "provider": "github",
  "name": "Production GitHub",
  "content": {
    "token": "REDACTED",
    "owner": "agent-barn",
    "org": "agent-barn",
    "repos": [
      "agent-barn"
    ]
  }
}

{
  "id": "018f0000-0000-7000-8000-000000000001",
  "organization_id": "018f0000-0000-7000-8000-000000000002",
  "provider": "github",
  "name": "Production GitHub",
  "created_by": "018f0000-0000-7000-8000-000000000003",
  "agent_count": 0,
  "created_at": "2026-08-29T10:00:00Z",
  "updated_at": "2026-08-29T10:00:00Z"
}

The response does not include content.

Attach it to an Agent

The Agent must be stopped.

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

{
  "shared_credentials": [
    {
      "shared_credential_id": "018f0000-0000-7000-8000-000000000001"
    }
  ]
}

Replace a manual credential with a Shared Credential

Remove the existing provider slot and attach its replacement in the same Agent update:

{
  "removed_secret_providers": [
    "github"
  ],
  "shared_credentials": [
    {
      "shared_credential_id": "018f0000-0000-7000-8000-000000000001"
    }
  ]
}

Detach it from an Agent

Detachment is expressed by provider through removed_secret_providers:

{
  "removed_secret_providers": [
    "github"
  ]
}

Rename a Shared Credential

PATCH /api/v1/organizations/{organization_id}/shared-credentials/{credential_id}
Content-Type: application/json

{
  "name": "Production GitHub — read only"
}

Renaming does not require the credential content, and does not replace the stored payload.

Replace credential content

Submit the complete provider payload:

{
  "content": {
    "token": "REDACTED_NEW_TOKEN",
    "owner": "agent-barn",
    "org": "agent-barn",
    "repos": [
      "agent-barn"
    ]
  }
}

The provider cannot be changed through this endpoint.

Validate a Shared Credential

POST /api/v1/organizations/{organization_id}/shared-credentials/{credential_id}/validate
Content-Type: application/json

{}

Delete a Shared Credential

DELETE /api/v1/organizations/{organization_id}/shared-credentials/{credential_id}

A successful deletion returns HTTP 204. An attached credential returns HTTP 409.

Troubleshooting

Security considerations

Follow these practices:

• Create dedicated automation identities instead of sharing personal credentials
• Grant the minimum provider permissions required
• Separate production, staging, and development credentials
• Use different credentials for Agents with different authorization boundaries
• Keep repository and workspace defaults narrow
• Test both allowed and prohibited resources after every change
• Avoid sensitive information in Shared Credential names
• Remember that all accepted Organization Members can list credential metadata
• Restrict Agent Secret management through Agent access roles
• Rotate credentials regularly, and immediately after suspected exposure
• Restart every attached Agent after a rotation, because the runtime receives content only at start
• Revoke old provider keys only after verification
• Monitor provider audit logs for actions performed by the shared identity
• Do not place provider secrets in Templates, Skills, Agent prompts, or source control
• Back up the Agent Barn encryption key according to your deployment policy, because losing it makes encrypted credential payloads unreadable
• Treat encryption-key rotation as a credential migration, not a normal provider-token update

Shared Credentials are also isolated by Organization. A credential owned by one Organization is not readable or attachable from another, even by a user who belongs to both.

Next steps

After creating and attaching a Shared Credential:

1. Validate the credential where live validation is supported.
2. Restart each attached Agent.
3. Test permitted and prohibited provider resources.
4. Record the credential owner and rotation schedule.
5. Review the number of attached Agents regularly.
6. Continue to Manage organizations and members.