Secret configuration

A secret is a named box that holds one credential — for example an API key, a personal access token, or the tokens obtained when you authorize an external service. Connections refer to a secret by its name, so a credential is registered once and can be rotated without editing the connections that use it.

The Secret page separates two things:

The declaration (this document) — which secrets exist, what they are for, which Team may use them, and how their value is provided. It is edited in Edit mode, version-controlled in History mode, and can be proposed by Buddy.
The value — the credential itself. It is never part of the document. It is entered in Ops mode (or, for grant secrets, written when you connect from the connection that uses the secret), and it is never shown again after it is saved.

Only Organization owners and admins can open the Secret page, view the declaration, or set values.

Spec fields

Field	Type	Required	Default	Notes
`secrets`	array	Yes	—	Every secret that should exist in the Organization. Use `[]` to declare none. The document is declarative: a secret that is left out of the list is deleted together with its stored value when the document is applied.

Each entry of secrets has the following sub-fields:

Sub-field	Type	Required	Default	Notes
`name`	string	Yes	—	The identifier connections use to refer to the secret. Starts with a letter or digit, followed by letters, digits, `_` or `-`; up to 64 characters. Must be unique within the Organization. Renaming a secret is the same as deleting it (and its value) and declaring a new one.
`description`	string	No	`""`	What the secret is for. Up to 500 characters.
`team_id`	integer \| null	No	`null`	`null` = any connection in the Organization may use the secret. Set a Team ID to limit it to that Team's connections. The Team must belong to the Organization. Deleting a Team deletes the secrets limited to it.
`kind`	string	Yes	—	How the value is provided: `static` — a person pastes the value in Ops mode; `grant` — the value is written when you connect (authorize) from the connection that uses the secret.

Ops mode operations

Ops mode shows each secret's value state — whether a value is set, its version, and when and by whom it was set — and offers the operations below. For a grant secret it also shows the connection state: the service it is connected to, whether it is connected, expired (the service rejected the stored tokens; connect again), or failed, and when the current access token expires. The value itself is write-only: it is never displayed or returned by the API.

A grant secret that holds tokens is tied to the service that issued them: a connection to a different service cannot use them or store its tokens there. Unit Oncall refreshes the tokens of a connected grant secret automatically.

Set value (static only) — saves a new value. Setting a value for the first time and rotating it are the same operation; the new value becomes the current one.
Roll back to the previous value (static only) — makes the value that was current before the last change current again. Only the current value and the one before it are kept, so you can go back one step.
Delete value — removes every stored value of the secret. The declaration stays, so you can set a new value later. Connections that reference the secret stop working (they show as Credential Missing) until a new value is set. For a grant secret this disconnects the service; connect again from the connection that uses the secret to restore it.

A value can be at most 16 KiB.

Validation rules

Unknown fields are rejected, both at the top level and inside an entry of secrets.
secrets must be present. Each entry needs name and kind.
name must match the format above and must not appear twice.
kind must be static or grant.
team_id must be the ID of a Team in the same Organization.
The kind of a secret that currently has a value cannot be changed. Delete the value in Ops mode first, then change kind.
A secret that a connection references (listed in View mode) cannot be removed from the list, change its kind, or be limited to a Team. Change the connection to use another secret first. Rolling back to a version that would do any of these is rejected the same way.
A value can only be set on a static secret. The value of a grant secret is written only by connecting from the connection that uses it.

Version history and rollback

The declaration is version-controlled: History mode lists every applied version with a diff, and any version can be rolled back to. Values are not part of the declaration, so they are not versioned there — but rolling back to a version that does not list a secret deletes that secret together with its value, exactly as applying such a document would. Entries are stored in name order, so reordering the list does not create a new version.

Audit log

Changes to the declaration, rollbacks, and every value operation (set, roll back, delete) are recorded in the Organization's audit log. The value itself is never recorded. See Audit logs.

Examples

A static token for a GitHub MCP connection, available to the whole Organization, and an authorized connection limited to one Team:

{
  "secrets": [
    {
      "name": "github-pat",
      "description": "GitHub MCP connection",
      "team_id": null,
      "kind": "static"
    },
    {
      "name": "notion",
      "description": "Notion workspace for the platform Team",
      "team_id": 42,
      "kind": "grant"
    }
  ]
}

No secrets declared:

{
  "secrets": []
}

MCP connection — the connections that use credentials.
Team — the Teams a secret can be limited to.
Audit logs — where secret operations are recorded.