Secrets & keys
The Secrets & keys section manages a fixed set of credentials that Colony uses to reach external services. You can set, replace and delete each value. You can’t add keys of your own. You’ll find the cards on Operations → Settings, under the line “Encrypted credentials for connecting workers to external services.”
Workers read these credentials. When you route them through this tenant’s model access, so do the Mayor, Colony’s readings, draft assists and the repository conventions check: the Colony Cloud API decrypts the key and sends it to your provider. Nobody can view a value again in the dashboard or API, including you.
A Claude subscription token isn’t one of these tenant secrets. If your organization may use a Claude subscription, set it per repository, in that repository’s Agent authentication drawer (Operations → Settings, choose the repository). The Secrets section links to each repository’s drawer.
Open the page
Section titled “Open the page”Go to Operations → Settings (Secrets). The page lives at /operations/settings.
Each key has its own card with a Configured or Not configured badge, a masked input and a Save button. The custom headers key uses a multi-line text box instead. A configured card also has a Delete button, except the two Pipeline Store keys.
The Anthropic card’s button reads Save the key, and it also has Check the key.
| Dashboard label | Shown when | What it’s for |
|---|---|---|
| Pipeline Store URL | You bring your own Pipeline Store | Postgres connection string for your Pipeline Store, where pipeline state (issues, PRs, costs) lives. Use the pooled or transaction connection string. Must start with postgres:// or postgresql://. |
| Pipeline Store Direct URL | You bring your own Pipeline Store | Direct (non-pooled) connection string, used for running migrations. Same postgres:// or postgresql:// prefix. |
| Anthropic API Key | Claude Provider is Anthropic, or a value is stored | Your Anthropic API key. Workers use it for LLM calls during analysis, development and review, and so do the Mayor and other features you route through this tenant’s model access. |
| Foundry API Key | Claude Provider is Azure Foundry, or a value is stored | API key for Azure Foundry. |
| Gateway Auth Token | Claude Provider is AI gateway, or a value is stored | Auth token for your AI gateway. Workers send it as ANTHROPIC_AUTH_TOKEN. |
| Gateway Custom Headers | Claude Provider is AI gateway, or a value is stored | Optional extra headers for your gateway, passed unchanged as ANTHROPIC_CUSTOM_HEADERS. One Name: value per line. |
| OpenAI API Key | Always | Your OpenAI API key. Made available as OPENAI_API_KEY in Worker containers, for setup and CI commands or tools that call OpenAI APIs. |
Which keys you see
Section titled “Which keys you see”- Pipeline Store keys. The two Pipeline Store URLs appear only for a BYO Pipeline Store. When Colony Cloud manages your Pipeline Store, they’re hidden and the page shows a note that connection details aren’t configurable.
- Claude credentials. A Claude credential shows when it is configured, or when it matches the Provider selected at the top of this section (Anthropic, Azure Foundry or An AI gateway). That control starts on the Claude Provider saved in Pipeline Config. It only changes which cards show, not the saved provider.
- Stored credentials for other providers. If you switch provider, credentials you saved for the old one stay visible, with the note “Not used by the current Claude provider”. That’s how you find and delete stale ones. Once deleted, an unused card disappears.
Set or replace a value
Section titled “Set or replace a value”- Open Operations → Settings (Secrets).
- Find the card for the key and paste the new value into its input.
- Click Save.
Saving overwrites the stored value, and the old one is discarded. The input is cleared after a successful save and the badge shows Configured. Replacing a value works the same way as setting it for the first time, so there’s no separate rotate step.
Saving the Anthropic key checks it with Anthropic first. A refused key isn’t saved. If Colony can’t reach Anthropic, the key is saved unchecked and a warning says so.
A value must meet these rules, or Save stays disabled:
- 2048 characters or fewer.
- No leading or trailing spaces or newlines.
- For Gateway Custom Headers, every non-empty line is in
Name: valueformat. - The value doesn’t belong to another provider. A Claude subscription token or
sk-ant-key in OpenAI API Key, or an OpenAIsk-key in Anthropic API Key, is rejected withSECRET_WRONG_PROVIDERand the message says where it belongs.
The API accepts only the keys in the table. PUT /api/orgs/:orgId/secrets (body { "key": …, "value": … }) with any other key is rejected with a 400 Invalid key response. DELETE /api/orgs/:orgId/secrets/:key accepts the same keys, refuses the two Pipeline Store keys with a 400, and returns 404 if no value is stored.
If your external service needs overlapping credentials, create the new one there before you save it here. For provider, BYO Worker, package-feed and database rotations, follow Rotate Credentials Without Stopping the Pipeline.
Delete a value
Section titled “Delete a value”Deleting needs the tenant-administrator grant. See Team & Roles.
- Open Operations → Settings (Secrets).
- Find the configured card and click Delete.
- In the Delete <label>? dialog, read the warning and click Delete. Workers will no longer receive this credential, and it can’t be undone. If features you route through this tenant’s model access use it, they can stop working until you add another.
A Secret deleted toast confirms it, and the page refreshes your setup readiness. The Pipeline Store keys have no Delete button, because removing them would cut your Workers off from pipeline state. Replace them instead.