Credentials and connections
Give your agents the access they need without handing them a single secret. A credential is a named secret a tool needs, such as a Git token, an API key or an OAuth sign-in. Marshal stores each value encrypted, and nobody can read it back after you save it, admins included. For API keys sent over HTTP, the agent only ever holds a placeholder: Marshal swaps in the real value on the way out, and only for the hosts the package declared.
A connection is a credential you create by signing in, for example “Sign in with GitHub”. The Connections page in the web app lists all your credentials, pasted or signed in.
What you can do with it
- One GitHub credential for the whole team. Create a credential owned by the Platform team and bind it in the team’s manifest. Every team member’s spaces push with it, and no member ever sees the token.
- Rotate without touching anything else. Replace the value of a leaked API key in place. The credential keeps its bindings and shares, so new spaces get the new value with no other change.
- Sign in once, work everywhere. Sign in with GitHub, bind the connection in your manifests, and every space you start can clone and push as you.
See it end to end: Let agents use secrets they never see.
How it fits
Marshal stores the credential, a manifest binding names it, and the space gets it at start. To reach the service host, Marshal injects the value into the tool, or swaps it in for a placeholder on the way out.
- A package defines the credential types it accepts, in the form
<package>.<method>, such asclaude-code.token. Thegithubpackage, for example, accepts a GitHub sign-in, a personal access token or an SSH key. - A manifest names which credential each package uses. A manifest always uses credentials from its owner’s scope. See Whose access a run uses.
- When the owner can reach more than one credential with the same name, the most specific wins: personal, then team, then organization.
- Inside the space, the value goes straight into the tool’s process, the agent sees a placeholder for HTTP keys, and a database password stays with Marshal while the agent talks to a local socket. A call that tries to send a key to any other host is blocked and audited.
How a sign-in gets its client identity
When you sign in to a service, the service needs to know which app is asking. Marshal calls that app the client identity, and an admin chooses where it comes from with a connect mode for each package, under Settings > OAuth apps.
In Automatic, the default, Marshal picks for you:
- Your org’s own app, if an admin enabled one.
- Otherwise Marshal’s Auth Broker, when it is on and can serve the service.
- Otherwise your cell registers a client with the service itself (DCR from this cell).
Admins can also pin Own app, Marshal app, DCR via broker or DCR from this cell. A pinned mode is the mode that runs. Changing it never disconnects anyone, because each connection keeps renewing the way it was made. See Integrations for what each mode does and when to pick it.
Sharing and ownership
A credential belongs to a person, a team or the organization. See Owners, teams and scope.
| Pasted value (API key, token, setup token) | Signed in (“Sign in with …”) | |
|---|---|---|
| Acts as you | No | Yes |
| Share with others | Yes | No |
| Change owner | Yes | No |
| Rotate | Yes | No, reconnect instead |
A credential you get by signing in acts as you, so it stays yours. Its row shows “Acts as you”. A share lets others use a credential without ever seeing its value, and it never gives the right to change, delete or re-share it. When you withdraw a share, new spaces lose access at once. A space that is already running keeps the value it holds, but cannot refresh it.
Launching with missing credentials
A space can start before every credential is in place. The tools that are missing a credential are in the space but not authenticated, and everyone who can see the space can see which ones. When the agent calls one of them, it gets a not_authenticated error that names the integration and returns at once.
Org owners and admins choose what happens under Settings > Configuration, in the Spaces group, with Launch With Missing Credentials:
| Value | What a launch does |
|---|---|
warn (default) | The space starts, the launch form lists what is missing, and the space page shows a badge and the list. |
error | The launch is refused, and the message lists the missing credentials. |
Some problems always refuse a launch, under both values: a credential that was withdrawn from you, one you can only see, or one the person running it may not use. Those are permissions, not gaps. This also applies to runs, which now check these before they start.
One more case always refuses, under warn as well: a run started with an API key or by a deputy whose agent has no credential it can reach. Nobody is there to sign the agent in, so the run would fail at once with “Authentication required”. The refusal names the credential and says to add one at org scope, or share it with the org. A space you launch yourself still starts, and the manifest list shows needs org credential until the credential is reachable.
A deputy can be made stricter than the org, never looser. Every change to the setting is recorded in the audit log.
Health
A credential is either OK or Needs reconnect. It needs reconnect when the provider says you must sign in again. It goes back to OK when you reconnect, or when a space renews the sign-in and the service accepts the renewed token. These credentials show on Home under “Needs attention”.
Related
- Share a credential with a team.
- Connect GitHub and Add a Claude credential.
- Add an HTTP secret.
- Integrations: connecting services in depth.