Secrets

The work an agent does on your behalf needs credentials: a model provider's API key, a token to reach your repository, the client secret for a connected drive. Disco Parrot holds those for you so you never paste a key into a prompt and an agent never carries one in the clear. You set a secret once; the platform keeps it, hands a short-lived, scoped version of it to a run that needs it, and gives it back to no one, not even you.

This page is about managing those secrets: where their values live, the difference between a workspace value and your own personal override, the rule that you can set a value but never read it back, and the managed and custom keys you work with. Secrets are reached under Settings → Secrets, and managing the workspace's secrets is gated by a role, covered in roles and permissions.

Where values live: your workspace vault

Each workspace has its own dedicated secret vault, a per-tenant Azure Key Vault that holds that workspace's secret values and nothing else. The value of a key, the actual token, lives only in the vault. What Disco Parrot keeps alongside it is metadata, never the secret itself: which key it is, whether it is a workspace value or a personal one, who last set it, and when. So the Secrets page can show you the full picture of what is set and by whom while the values themselves stay in the vault.

That the vault is per workspace is the reason a secret in one workspace is genuinely unreachable from another. There is no shared key store to leak across tenants; each workspace's credentials sit in its own vault, provisioned for it alone. The vault's status surfaces on the Secrets page, and what it means when it is still coming up is covered below.

What needs a secret

Before the mechanics, it helps to see what actually draws on a secret, because it is more than you might expect. A model run reaches for a provider API key. A git clone into a sandbox reaches for a repository token. An MCP server reaches for whatever it authenticates with. A sandbox profile can name a custom key its runs need. A connected drive reaches for its client secret. Each of these is a credential the platform holds for you and hands to the work at the moment it runs, never before and never to keep. The rest of this page is how you set those credentials and how the platform keeps them safe.

Tenant secrets and personal overrides

A secret can be set at two levels, and the difference is who it applies to.

A tenant secret is a workspace value: set it once, and every member's runs use it. This is the common case, the team's shared provider key or repository token, managed by an administrator so nobody else has to think about it.

A personal override is your own value for a key, used only by your own runs. It sits on top of the tenant value without changing it for anyone else. An engineer who wants to run against their own model-provider account, or their own repository token, sets a personal override and leaves the team's value untouched.

When a run needs a key, Disco Parrot resolves it in a fixed order: your personal override first, then the workspace value, then the platform default where there is one. The first one that exists wins.

The order is what makes both levels useful at once. A workspace can set a single shared key that everyone falls back to, and any individual can run on their own without disturbing it. The Secrets page labels each key with where its current value is coming from, your override, tenant configured, platform default, or not set, so the resolution is never a guess. A platform default is a fallback the operator may supply for some managed keys; you cannot see or set it, and a run only reaches it when neither a personal override nor a workspace value exists. If a key a run needs has no value at any of the three levels, the run does not receive that credential, so set the keys your work depends on.

Your personal overrides are yours alone. An administrator sees the workspace values and who set them, but not whether you have set an override of your own; your overrides are visible only to you.

Set a value, never read it back

This is the rule that makes the whole system safe to use. The moment you save a value it goes into the vault, and from then on every screen and every read shows only that the key is set, who set it, and when. There is no reveal button, no copy-the-value action, no API that returns the plaintext. Replacing a value is the same action as setting one: the new value overwrites the old in the vault, and runs pick it up on their next lease, which is exactly how you rotate a key. Removing a value asks you to confirm first, so a credential is never cleared by a stray click.

That holds all the way to the agent. A secret never reaches a run as a plain environment variable it could print or leak. When a run genuinely needs a credential, the platform mints a short-lived, scoped lease of it and delivers it through the narrowest channel the task allows. That might be a credential helper for git, a temporary file, or a single process's input. Then it expires. The agent gets the use of the key for the moment it needs it, and never the key itself to keep. The full delivery model, the phases and the channels, is the subject of the secret policy, and the grant itself is credential leases; here the point is simpler: a value you set is a value you grant the use of, not a value you, or anything else, can read out again.

Managed keys and custom keys

Disco Parrot knows about the credentials its own integrations need, and it lets you define your own on top.

Managed keys are the well-known credentials the platform's features consume, and the Secrets page lists the handful most workspaces set directly: the model-provider API keys for the AI runtimes (Anthropic, OpenAI), the GitHub token and the Copilot token, and the personal access tokens for your GitHub and Azure DevOps integrations. The platform already knows what each one is for, so you set it and the feature picks it up.

Two things keep that list honest. The integration tokens appear only once you have connected the GitHub or Azure DevOps integration they belong to, so a workspace that has not set those up never sees rows for credentials it has no use for. And a few other credentials the platform manages, the client secrets for Google Drive and OneDrive and the webhook for Teams notifications, are set inside their own connection flows rather than on this page, because that is where you are when you need them.

Custom keys are your own. When a sandbox profile or a runtime setting needs a credential the platform does not know about, you create a custom key for it. A key name has to be uppercase letters, digits, and underscores, starting with a letter (^[A-Z][A-Z0-9_]*$), so STRIPE_API_KEY or INTERNAL_SERVICE_TOKEN are fine and the editor holds you to that shape. Once created, you reference a custom key as secret:KEY in the places that take one: a sandbox profile's configuration, an MCP server's settings, an SDK config. The platform resolves the reference to the current value at run time, through the same vault and the same value-never-returned rule as a managed key.

Like managed keys, a custom key can be a workspace value or a personal override. The one difference is the depth of the ladder: a custom key has two levels, your override and the workspace value, and no platform default, because there is no operator fallback behind a credential the platform does not ship. If neither level is set, a profile that references secret:STRIPE_API_KEY receives nothing, the same as any unset key, so set the value before you point a run at it.

When the vault is still coming up

A workspace's vault is provisioned for it the first time a secret is set, and that takes a moment. The rest of the workspace, the projects and plans and people, never depends on the vault; only secrets do, which is why this is the one place its status matters.

A value you try to set while the vault is still coming up is declined with a clear "try again in a moment," rather than failing in a way you have to puzzle over. Everyone in the workspace sees the status while the vault is provisioning; the Retry on a failed vault is an administrator's to press, and it starts provisioning again. It is the only recovery you need, and it is a single action.

Who can set secrets

Setting a workspace value is an administrator action, on the secrets.tenant.manage scope, held by the Owner, Admin, and Workspace Operator roles, the same Workspace Operator who owns the rest of the tooling. Setting your own personal override is open to everyone, on the self-only secrets.user.manage scope, because your own values are yours to manage and no one else's to touch.

Seeing the workspace's keys at all, even just which ones are set and who set them, takes secrets.tenant.read, which the same three roles hold. A plain member still has the Secrets page and manages their own personal overrides there, but the shared workspace credentials, and the record of who last changed each one, stay visible only to the administrators whose job it is to manage them. Each workspace value shows its setter and timestamp, so rotating a key leaves a clear trail for the people who own it.

This is how Priya Patel runs against her own model-provider account without disturbing anyone. The team sets ANTHROPIC_API_KEY once as the workspace value, and her runs use it like everyone else's. When she wants her own billing for a stretch of work, she sets a personal override for that key; her runs switch to her account, and no one else's change. Later, when Sarah Chen rotates the team's value, she replaces one value in one place, and Priya's override sits untouched on top of it. Two people, two accounts, one key name, and neither one steps on the other.

Why secrets work this way

The decision that shapes everything else is that a value you set is a value you can never read back. It sounds inconvenient until you sit with what it prevents. A secret that cannot be read out cannot be exfiltrated through the product, cannot be screenshotted off a settings page, cannot be returned by an API that someone points a script at, and cannot be printed by an agent that was talked into trying. The cost is that you keep your own copy of a key somewhere you trust if you will need it again; the benefit is that the place you stored it in Disco Parrot is not a place it can leak from. For a product whose whole job is to let agents act, a write-only secret store is not a limitation to apologize for. It is the property that makes handing an agent real credentials defensible.

The resolution order is the other quiet choice. A workspace wants one shared key it can manage centrally; an individual sometimes needs to run on their own account without filing a request or disturbing the team. Resolving your override, then the workspace value, then the platform default, gives both at once: central by default, personal when you need it, and always legible about which one is in play. And keeping each workspace's values in its own vault means the boundary between organizations is enforced where the secrets actually live, not by a filter that has to remember to apply.

For a team lead, secrets are how your team's agents get the access they need without anyone handling raw keys. Set the workspace's provider key and repository token once, and every run your team starts uses them, with nobody pasting a credential into a chat.

For an engineer, a personal override is how you run on your own account when you want to, without touching the team's value or asking anyone's permission. And because nothing reads a value back, you never worry that a key you set is sitting somewhere it could be read off a screen.

For an administrator, the Secrets page is one console for the credentials the whole workspace runs on, with each key showing who set it and when, the vault standing per workspace, and a single retry if it ever needs one. You manage the shared keys; everyone manages their own overrides; nobody manages anyone else's.

For the person who owns security, this is the answer to "where do the keys live and who can read them." Values sit in a per-tenant vault, never cross to another workspace, and are never returned by any read, by anyone, including the agent that uses them. A credential reaches a run as a short-lived, scoped lease through the narrowest channel the task allows, and then expires. The keys are present enough to do the work and absent enough that there is nothing to leak.