Credentials and secrets
Two related things live here:
- A coding-agent credential is the model-account credential the agent itself runs on. Without one, nothing launches.
- A secret is any other encrypted value you want an agent to be able to use — a deploy key, an API token, a database password.
Almost everything on this page is a thing that fails quietly if you assume the wrong answer, so it is worth reading once end to end.
Coding-agent credentials
The types
| Agent | Credential | Looks like | Personal only? |
|---|---|---|---|
| Claude Code | API Key | sk-ant-api03-… | no |
| Claude Code | OAuth Setup Token (Claude subscription) | sk-ant-oat01-… | yes |
| Claude Code | AWS Bedrock | AWS key pair + region | no |
| Claude Code | Google Vertex | service-account credential + project | no |
| Codex | API Key | sk-… | no |
| Codex | ChatGPT Subscription | a subscription token | yes |
Where each comes from is in step 1 of setup.
Subscription credentials are personal by construction. An OAuth setup token and a ChatGPT subscription token represent one human's personal subscription, so the platform will only ever store them as personal credentials. They can never become an organization's shared credential — that is enforced, not a convention.
Personal vs shared
| Personal | Shared | |
|---|---|---|
| Stored on | your account | the organization |
| Who can use it | you | everyone in the organization |
| Who can create it | you | an owner or admin |
Resolution is personal-first for the owning user. If you have a personal credential, your own sessions use it and everyone else falls back to the organization's shared one.
Sessions nobody started require a shared credential. An alert-triggered run or a service principal has no personal credential to resolve. An organization whose only credential is somebody's personal subscription token can run interactive sessions and nothing else — the automated paths will fail with no credential found.
A shared credential still has to reach the workspace
A shared credential is not automatically usable everywhere. When it is created you choose between:
- Available to all workspaces — usable anywhere in the organization; or
- specific workspaces — choose the workspaces that can use this.
A credential scoped to particular workspaces resolves in those and nowhere else. This is the most common reason a perfectly valid, active shared credential does not satisfy the setup checklist in some workspace: it was never assigned to that one. Change it in the connection's settings at any time.
Two other things make an otherwise-good credential stop resolving: it has expired, or it is no longer active.
Connecting one picks your default coding agent
Your organization starts with two agent definitions, one per coding agent, and
neither flagged as the default. Connecting a credential in the setup wizard flags the one that
matches: connect Codex and Default (Codex) becomes the default; connect Claude and Default does.
So the order matters slightly — connect the credential for the coding agent you actually intend to use, and the rest follows. → No default coding agent yet
Once a default exists, the setup checklist checks for that coding agent specifically. A Codex credential will not satisfy it while Claude is your default, even though the credential is perfectly valid. That is deliberate: without it you would be told everything was ready and then fail inside the container with an authentication error that points at nothing. Either connect a credential for the default coding agent, or change the default to the one you have.
Frozen at launch
When a runtime starts, PlatformSmith resolves the coding-agent credential once and freezes it into that runtime instance. Every session in that container inherits the frozen value.
Rotating, replacing or deleting the credential afterwards has no effect on anything already running. To pick up a new credential you need a fresh runtime — not a restarted session, not a reconnect, not a new message.
Practical consequences:
- Rotating a leaked key is not complete until the runtimes that were holding it are gone. Stop them.
- "I fixed the key and it still fails" almost always means the container predates the fix.
- Testing a new credential means launching something new, not retrying in the old container.
Secrets are write-once
You can set a secret value and you can replace it, but you cannot read it back — not in the UI, not through the API, not through the MCP server. There is no "show value".
So rotation means revoke and re-add, and it means you need the value from wherever you originally got it. If the only copy of a credential is the one you pasted into PlatformSmith, you no longer have a copy.
Secrets
Scopes
A secret lives at organization, workspace or project scope, and may additionally be pinned to one environment.
Resolution is innermost-scope-first, with the environment pin breaking ties within a scope — not acting as a fourth scope. The full rule, with a worked example, is on Configuration precedence.
How an agent gets one
An agent definition declares which secrets it may use — the reference is attached to the definition, not to the agent or the container. At launch, the platform resolves those references against the launching scope and injects the values into the container.
That has a consequence worth stating plainly: an agent can see the secrets its definition asks for, and no others. Adding a secret to a project does not make every agent in the project able to read it; some definition has to reference it.
What the platform can and cannot see
- PlatformSmith stores secret values encrypted and does not return plaintext through any API, including the MCP control plane, which refuses by design.
- A coding agent inside your container receives the values its definition references, because it needs them to work. Treat the container as having them.
- Anyone who can edit an agent definition in a scope can, in principle, cause that scope's secrets to be injected into a container they can reach. That is what the definition editing permission means — see Security and tenancy.