Credentials and Secrets

Credentials supply authentication to Agent Runtime, MCP servers, skills, plugins, and Knowledge connectors. Manage them under Settings → Credentials. Credentials are available without enabling Agent Runtime.

Credential Types

A Custom secret holds one value, such as a GitHub personal access token. The integration determines how that value is used.

A GitHub App always belongs to the organization. It holds an API URL, app ID, installation ID, and private key. Archestra uses the private key to request an installation token. Agent and MCP environments receive the token, never the private key.

Installation tokens expire after one hour. Archestra renews them for managed runtimes. See Token Refresh for process behavior.

Install the GitHub App on the repositories it needs. Its installation permissions determine the token's access. Individual integrations describe their required permissions.

A GitLab token always belongs to the organization. Skills, plugins, and Git sync use it for gitlab.com and self-managed GitLab.

• It holds a GitLab URL and an access token.
• You add it while you pick a GitLab repository. See Private Repositories.
• Archestra checks the token with GitLab before it saves it.

A GitHub user credential links your account to an organization-managed App. Authorize once through GitHub. Every harness using that credential acts as your GitHub user. Access is limited to permissions held by both you and the App.

The organization App needs an OAuth client ID and client secret for personal authorization. Register <frontend URL>/settings/credentials/github/callback as its callback URL. Keep expiring user authorization tokens enabled. Personal authorization requires writable secret storage.

GitHub user credentials and installation credentials have separate ownership policies. Interactive coding agents can use personal credentials. Unattended agents can use the organization's installation credential.

Ownership

Every credential definition has a name, description, type, and owner policy. Its saved values are separate from that definition.

Each user means every person connects their own private value. Agent Runtime uses the person acting on the run. MCP servers use the owner of a personal installation. Another user's value is never substituted.

With Agent Runtime enabled, Account → Credentials appears when a personal credential is available. Installed Claude Code agents also make the page available.

The organization means an administrator connects one shared value. Scheduled skill, plugin, and Knowledge syncs use organization credentials.

Create separate definitions when the same service needs both ownership policies. A personal MCP credential cannot be used by an organization installation.

Who Can Manage a Credential

Decide, credential by credential, who sees it, connects to it, and changes its shared value. For example, let the platform team rotate one GitHub App's private key without reaching any other credential.

• One credential: click Edit on its row, then open Permissions.
• Every credential: open More actions beside Add credential, then choose Permissions.

Each recipient gets a level:

• Can view: sees the credential and where it is used.
• Can use: also connects a personal value, and binds it to a guardrails battery.
• Can edit: also changes its details and its organization value.
• Full access: also deletes it and manages who else can reach it.

What to know:

• Opening Settings → Credentials needs credential:read. Adding one needs credential:create, and its creator gets Full access.
• A new credential is shared with Everyone in the organization at Can use, and admins and editors have Full access to every credential. Remove the Everyone grant to keep a credential to a team.
• Attaching a credential to an MCP server or Agent takes Can use on it. Once attached, its organization value works for anyone who can use that server or Agent. A personal value needs Can use. Without it, the MCP server's Install button is disabled and the Agent's chat says "You don't have access", both asking you to get an admin to share it. See Granular Access Control.

Secrets Storage

Saved credential values use the configured secrets manager. Archestra stores them in its PostgreSQL database by default, or in HashiCorp Vault when external secrets storage is configured. Configure your storage provider under Settings → Secrets.

The Credentials page displays connection status without revealing stored secrets. LLM provider accounts and native Claude subscriptions retain their dedicated sign-in flows.

Database Storage

Database storage is the default. To configure it explicitly, set ARCHESTRA_SECRETS_MANAGER to DB.

Stored secrets are automatically encrypted at rest using AES-256-GCM derived from ARCHESTRA_SECRETS_ENCRYPTION_SECRET. Existing plaintext secrets migrate to encrypted format on startup.

Key Rotation

To rotate the encryption key without losing access to stored secrets:

1. Set ARCHESTRA_SECRETS_ENCRYPTION_SECRET to the new key.
2. Set ARCHESTRA_SECRETS_ENCRYPTION_SECRET_PREVIOUS to the old key.
3. Restart Archestra. The platform re-encrypts stored secrets under the new key on startup.
4. Remove ARCHESTRA_SECRETS_ENCRYPTION_SECRET_PREVIOUS on the next deployment.

Startup verifies the active key against stored secrets and aborts if it cannot decrypt them. To accept a new key without re-encrypting older secrets, set ARCHESTRA_SECRETS_ACCEPT_NEW_ENCRYPTION_KEY=true for one boot. Unmigrated secrets remain unreadable and must be reconnected.

HashiCorp Vault

HashiCorp Vault stores secret values externally instead of in the database. Only references to Vault secret paths are stored in PostgreSQL.

[!NOTE]
HashiCorp Vault storage requires an Enterprise license. Contact sales@archestra.ai for licensing.

Set ARCHESTRA_SECRETS_MANAGER to VAULT and configure the connection parameters:

If ARCHESTRA_SECRETS_MANAGER is set to VAULT but required variables are missing, Archestra logs a warning and falls back to database storage.

Vault paths are formatted as {prefix}/{secretName}. The default prefix depends on the KV engine version: secret/data/archestra for KV v2 and secret/archestra for KV v1.

Vault Authentication

Archestra supports three authentication methods for connecting to HashiCorp Vault:

• Token: Set ARCHESTRA_HASHICORP_VAULT_TOKEN.
• Kubernetes: Set ARCHESTRA_HASHICORP_VAULT_K8S_ROLE. Optionally customize ARCHESTRA_HASHICORP_VAULT_K8S_TOKEN_PATH and ARCHESTRA_HASHICORP_VAULT_K8S_MOUNT_POINT.
• AWS IAM: Set ARCHESTRA_HASHICORP_VAULT_AWS_ROLE. Optionally configure ARCHESTRA_HASHICORP_VAULT_AWS_MOUNT_POINT, ARCHESTRA_HASHICORP_VAULT_AWS_REGION, ARCHESTRA_HASHICORP_VAULT_AWS_STS_ENDPOINT, and ARCHESTRA_HASHICORP_VAULT_AWS_IAM_SERVER_ID.

Using Credentials

Agent Runtime and MCP environment editors share the same Secret source selector. Choose a saved credential and enter the variable name expected by the runtime. One credential can supply GITHUB_TOKEN in one resource and GH_TOKEN in another.

A resource-specific secret supplies only that resource. Use a saved credential when several resources need the same value.

Conversation setup links check all required credentials after GitHub authorization. Complete any remaining credentials, then send your message again in the original conversation. Connecting credentials does not automatically retry the request.

Skill and plugin imports and policy sync use a GitHub App or a GitLab token. GitHub Knowledge connectors select an organization credential. See Skills, Plugins, and Knowledge for repository setup.

Rotation And Disconnection

Replacing a value updates future resolutions wherever the credential is referenced. For static secrets, restart MCP processes or start a new Agent Runtime run.

Skill and Knowledge operations resolve GitHub App tokens when they authenticate. Managed runtime tokens also renew during execution. Personal GitHub credentials refresh automatically while their authorization remains valid. Expired or revoked authorization requires reconnecting through GitHub.

Disconnecting removes a saved value without removing its definition. Required bindings need a connected value before execution. Deleting a definition is blocked while a resource references it.

Token Refresh

MCP servers receive renewed tokens through a managed process restart. Existing calls finish before renewal. New calls receive a retry response while the server drains and reconnects. Shared installations renew their common process together. Failed tool calls are never replayed automatically.

Agent Runtime keeps its running process and workspace. The built-in Agent reads renewed values before each shell command. Maintained images refresh GitHub authentication for each gh invocation, including Git credential-helper requests.

Custom runtime code reads the file named by ARCHESTRA_AGENT_RUNTIME_CREDENTIALS_FILE. It contains a taskId and a credentials object keyed by environment-variable name. Each entry has a value and expiresAt, expressed in Unix milliseconds. Read the file again before authenticating, and reject expired values. Kubernetes updates this file without restarting the process.

Environment variables remain startup snapshots. A custom process that caches one token still loses access when it expires. This also applies to commands that outlive a token and keep reusing it. Start a new command or make the client reread the managed file.

Provider failures delay renewal. Tokens keep their original expiry. MCP calls fail until renewal succeeds. Managed Agent commands refuse expired or unavailable credentials. Retained interactive sessions keep renewing until workspace cleanup. Disconnecting the credential or canceling the run prevents further renewal.

Use Case: One GitHub Credential Across Integrations

Save a GitHub token as an organization Custom secret named Repository access. Connect its value once.

Select Repository access for a coding Agent's GITHUB_TOKEN environment variable. Select it again for a GitHub MCP server's GITHUB_PERSONAL_ACCESS_TOKEN variable. Use the same credential for a GitHub Knowledge connector.

For personal repository access, create a GitHub user credential referencing the organization App. Each person authorizes GitHub once. Select that credential for each coding harness and personal MCP installation.

A GitHub App follows the same reuse pattern. Save its installation details, connect the private key, and select the credential in each integration.

Upgrading

Existing GitHub tokens become custom secrets. GitHub App configurations and runtime connections move into the shared credential store. Existing secret references and skill or plugin links are preserved.

This migration requires a coordinated upgrade. Stop older application replicas before applying it. Start the updated replicas after the migration completes.