Managed connections to external services: OAuth accounts, API keys, and MCP servers.
Credentials vs. secrets
The vault holds both, and they solve different problems:
| Credentials | Environment secrets | |
|---|---|---|
| What | Managed connections (OAuth sign-ins, provider API keys, MCP authorizations) | Raw encrypted key-value pairs |
| Lifecycle | The platform refreshes tokens and tracks status | You paste and rotate values yourself |
| Best for | Google, Slack, Atlassian, model providers, MCP servers, and API keys for any service | Values that belong to no service |
Both live inside a workspace's vaults. Every workspace has a default vault, and workspaces can create more to organize connections by project or environment.
Connection scope
Every credential has a scope that decides who can use it:
| Scope (API) | Who can use it | Who can create it |
|---|---|---|
only you (user) | Only you, in the workspace where you connected it | Anyone |
workspace (team) | Everyone in the workspace | Workspace admins |
org (org) | Every workspace in the organization | Org admins |
MCP server authorizations default to only you (user) scope: connecting Atlassian, for example, authorizes your account, and results follow your permissions in the external service. Another member can never act through your personal connection; the runtime refuses it.
Shared (workspace or org) connections are the fallback for service accounts: connect once with --as team or --as org from the CLI, or from the connection page as an admin. When both exist, a personal connection takes precedence over a shared one.
One boundary worth knowing: a personal connection belongs to you in that workspace. Switching to another workspace means connecting again there. Your live grants never leak across workspaces.
Connecting
- Web: open the service under connectors or the vault and click connect; OAuth happens in your browser.
- CLI:
belt credentials connect <provider>for OAuth and service accounts,belt mcp connect <slug>for MCP servers, or add keys directly in the vault.belt credsis an alias forbelt credentials.
Apps declare the credentials they need under credentials: in their inf.yml, by provider or by capability. At run time the platform injects the matching credential, choosing by scope and precedence: your own, then the workspace's, then the org's. If nothing is connected, the run tells you what to connect, or asks for the API key right there. See Declaring credentials.
API keys for providers we don't list
Adding an API key doesn't require the platform to know the provider. In add credential → API key, type the provider's name. The picker offers to add it as your own provider, and you can give its website. The key is saved as a credential for that provider, with its logo taken from the website.
Apps that declare the provider under credentials: find the key there, and so does every later key for the same provider.
Attaching an existing secret
A key saved as a plain secret can become a provider's credential without re-entering it. On the vault's secrets tab, the link icon opens attach to a provider: pick or type the provider and choose who can use it. The secret keeps its key name, so apps read it the same way.
The broken-link icon on an attached secret detaches it back to a plain secret. The same operation is PUT /secrets/{key}/provider in the Secrets API.
Disconnecting
Disconnect your account removes your OAuth tokens (or service-account material) and deletes the credential row. It does not remove a team's OAuth app credentials (client_id, client_secret, signing secrets, and similar keys from the provider's BYOK form) when those secrets are linked to the same row — for example a platform-managed Slack app or keys you saved for a custom auth scheme. If app keys are still present, disconnect is blocked until you delete those vault secrets first. Reconnecting after expiry replaces tokens only and leaves the OAuth app keys in place.
Security
Credentials are encrypted at rest, never logged, injected only at runtime into apps that declare them, and revocable at any time from the vault. Revoking on our side does not revoke the grant at the provider — do both when offboarding.
API and SDK references
- Credentials REST API: connect, list, and check requirements.
- JavaScript SDK: credential types:
CredentialDTO,CredentialConfigDTO, and related constants in@inferencesh/sdk - Python SDK: generated types:
CredentialDTO,CredentialConfigDTO,CredentialGrant,CredentialScope