Machine identities
What a machine identity is, how permissions and credentials relate to it, and where every screen lives in the console.
A machine identity is a non-human actor: a CI pipeline, a deploy job, a server, an agent. It is
the thing your audit log names when a secret is read at 03:00 — deploy-web@service-account, not a
person who happened to own the token.
Everything about the feature follows from one three-layer model. Get this and the rest of these pages are detail:
| Layer | What it is | Where it changes |
|---|---|---|
| Identity | who the machine is — a name, a slug, a lifecycle | Machine identities → the identity's page |
| Permissions | what it may reach — policies attached to the identity | Permissions tab |
| Credentials | how it proves itself — one or more pv_live_… API keys |
Credentials tab |
Permissions belong to the identity, not to the key. Two keys of the same machine differ only in their envelope — expiry, IP allowlist, rate limit — and in whether they were narrowed to a subset. Never create a second identity where a second key would do: the second identity has its own permissions to keep in sync, and nothing in the audit trail will tell you they were meant to be one actor.
Where it lives#
Inside a project workspace, under Secrets → Machine identities:
| Screen | Answers |
|---|---|
| List | which machines exist here, are their credentials healthy, what expires soon |
| Identity page | one machine: its credentials, permissions, activity, and CI setup |
| Ledger | who created, changed, disabled or archived what — including archived identities |
The identity page carries four tabs, and they map onto the questions in the order they get asked:
- Credentials — the keys, their status, scope, network envelope and expiry.
- Permissions — what this machine may reach, and attaching more.
- Activity — what it actually did, and why anything was refused.
- Setup — copy-paste snippets for consuming secrets from CI.
Above the tabs sits the blast radius panel, deliberately not behind a click: it resolves the machine's patterns against the project's real secret paths and answers "reaches 16 secrets across 3 environments, prod included" rather than "holds 4 policies". One is a decision input; the other is a count.
Pinned or space-wide#
A machine identity is either pinned to one project or space-wide (visible to every project in the space). The list shows both — a space-wide identity is not an error state, it is how you model a runner that serves the whole organization.
The choice is made in the creation wizard and can never be changed — not pinned later, not unpinned later. A pinned identity cannot be re-pinned to another project either. If you get it wrong, create a new identity; there is no migration, because "which project owns this machine" is exactly the kind of fact that must not quietly move under an audit trail.
A space-wide identity's page carries a banner saying so, because disabling or revoking it there affects every project that depends on it.
Status, and what each one means#
| Status | Its keys | How you get here | How you leave |
|---|---|---|---|
| Active | work normally | created, or re-enabled | disable |
| Disabled | all refused immediately | disable — the break-glass switch | re-enable, or archive |
| Archived | revoked permanently | archive (only from Disabled) | restore → lands in Disabled |
The full transition rules, and why restore does not return you to Active, are in Lifecycle & rotation.
Who can do what#
Each action needs a secrets:* permission. An organization's administrator role carries all of them
unless your organization changed it; a custom role holds only the ones it was given. In a personal
space the owner holds all of them.
A project's own Admin and DevOps members can manage that project's machines, if your organization
turns it on under DevOps → Permissions. They can then create its machine identities, issue and
revoke their keys, and create and attach permissions pinned to the project — and nothing outside it.
Even then they can never touch another project or a machine with no project, grant access across
environments or to shared, or remove a restriction someone else added. Viewers of the project can
see its machines but change nothing. With the setting off, only the permissions below count.
That limit follows the key, too. If an administrator gave one of the project's machines access
across environments or to shared, a project member cannot hand that access to a key: a key they
issue or re-scope must leave it out. Pick the key's permissions explicitly. A key with no
permissions chosen inherits everything its machine holds, so it would be refused.
On the organization's Machine identities page, a project member sees only the machines of projects they belong to.
| Action | Permission |
|---|---|
| Create, rename, disable, archive, restore an identity | secrets:service_account:manage |
| Issue, re-scope, change settings, revoke a key | secrets:api_key:manage |
| Attach or detach a permission | secrets:policy:manage |
| See what a machine's permissions are | secrets:secret:read or secrets:policy:manage |
| List every machine identity in the organization | secrets:secret:read, secrets:policy:manage or secrets:service_account:manage |
Reading the Permissions tab is a lower bar than changing it. If the tab tells you it cannot show you this machine's permissions, that is a statement about you, not about the machine — it says nothing about what the machine can actually reach.
Which roles hold these by default, and how to delegate one without making somebody an organization administrator, is on Who may see and change permissions.
Read next#
- Creating a machine identity — the wizard, step by step
- API keys — issuing, the one-time token, lifetimes
- Re-scope & settings — changing a live key
- Permissions — attaching what a machine may reach
- Activity & troubleshooting — why a call was refused
- Lifecycle & rotation — rotate, disable, archive, delete