# People, agents and access

> People, machines and agents get access in the same terms, scopes, through workspace roles and tokens that last five minutes at most.

Three kinds of principal act in a Golem workspace: people, who sign in to the console; machines, which enroll with an enrollment key and run the Golem agent; and agents, which register over OAuth to use Golem's MCP tools. All three are granted the same thing, a set of named scopes, and every token any of them holds lasts five minutes at most. People and machines manage this under **Settings → Identity and Access Management**.

## People

### Signing in

People sign in at [app.golem.team](https://app.golem.team) with an email and password, or with **Continue with Google**. An email address must be verified before it can do anything in a workspace. Golem does not yet offer SAML single sign-on or a second factor of its own; if you sign in with Google, your Google account's own controls apply.

### Roles

Every person holds exactly one of four roles. The role is their whole grant.

| Role | What it can do |
|---|---|
| Owner | Everything, including billing, deleting rules, releasing a quarantined machine, and managing other owners |
| Admin | Manage members, enrollment keys, rules and settings; place quarantines, legal holds and exports. Not billing changes, deleting rules or releasing a quarantine. |
| Member | Read and work with workspace data: read conversations and payloads, raise and resolve flags, approve held calls, check safety |
| Viewer | Read only: conversations and flags (not payload bodies), rules, quarantines and usage |

Only an owner can make someone an owner, and a workspace always keeps at least one.

### Inviting people

Under **Settings → Identity and Access Management → Members**, choose **Invite member**, give an email address and a role. The invitation takes effect the first time that address signs in with a verified email. Admins and owners invite, change roles and remove people.

If your organization has a verified email domain, **Settings → General** can let people from it join on their own: **Nothing**, **Ask to join** (an admin approves each request) or **Join** (straight in, with the role you choose, at most admin).

## Machines

A machine joins your workspace once, with an **enrollment key** (it starts `glk_`). Admins create them under **Settings → Deploy → Install** with **Create enrollment key**. The key is shown once, and the install command in the console already contains it:

```bash
curl -fsSL https://app.golem.team/install.sh | GOLEM_WORKSPACE_KEY=glk_... sh
```

The installer passes the key to `golem join` and does not store it anywhere on the machine. Joining creates the machine's own identity key (see [Hardware-backed keys](/record#hardware-backed-keys)), and from then on the machine proves who it is with that key, not with the enrollment key. It trades a signed proof for a fresh five-minute token whenever it needs one.

What a machine may do is set by role and scopes on the machine or its group, under **Identity and Access Management → Access**, in **Hosts**. Admins can define their own roles for machines and groups under **Roles** with **New role**. A machine with nothing set holds `context.read` and `rules.read`, and no more.

## Agents

Agents that use Golem's MCP tools (Golem Context and Golem Safety) register with Golem's OAuth service and receive a client id and secret. They exchange the secret for a token that lasts five minutes at most, and simply exchange it again when it runs out. There are no long-lived tokens.

| How it registers | Who is involved | What it can get |
|---|---|---|
| Headless, with an enrollment key | No person at the time; it needs the key a person issued | `safety.check` and `context.read` only |
| Device flow | A person approves it in the console | Any scope, as the person approves |
| Instant trial, no key | Nobody; it starts a new trial workspace | Safe scopes only, plus a workspace key that enrolls up to 3 machines so the trial can record. Unless a person claims it within 7 days, the trial is erased with everything it recorded. |

[auth.md](https://app.golem.team/auth.md) describes each flow for an agent's developer.

### Approving an agent

In the device flow the agent shows a code such as `BCDF-GH23` and a link to `app.golem.team/activate`. That opens **Settings → Deploy → AI agent approvals**:

1. Enter the code under **Approve an agent** and choose **Continue**.
2. Read what it asks for under **It will be able to:**. Each scope is listed in plain words.
3. Choose **Approve**, or **Cancel**.

A code expires after 10 minutes. At present only the account that created the workspace can approve.

### Scopes

| Scope | What it allows |
|---|---|
| `context.read` | Read ledger events, conversations, sessions and flags: metadata only |
| `artifact.read` | Fetch payload bodies: full prompts, tool arguments, API payloads |
| `safety.check` | Ask whether a proposed action is safe |
| `flags.write` | Raise and resolve flags, and work cases |
| `rules.read`, `rules.write`, `rules.delete` | Read, write and delete rules |
| `guard.read`, `guard.write`, `guard.release` | See, place and release quarantines and safe-mode clamps |
| `gate.approve` | Approve a held call so it runs |
| `intel.lookup` | Send an indicator to outside threat-intelligence sources, which costs money and tells them something from your traffic |
| `apm.read` | Read cost, tokens, latency and errors |
| `assets.decide` | Allow, alert on or block items in the Security Inventory |
| `agents.read`, `agents.revoke` | See the AI agents that use Golem with access of their own, and revoke one |

No scope implies another. A token carries exactly the scopes granted, and Golem checks them on every call.

## Nobody grants more than they hold

When a person gives a machine or a group a role or scopes, or defines a custom role, Golem checks every scope against what that person holds, and refuses any they do not have: "you do not hold `rules.delete`, so you cannot grant it". Assigning a role is checked by what the role contains, so an admin cannot hand out an owner's scopes by assigning a role that has them. Someone allowed to edit a single profile or rule set can narrow what its machines read, never widen it. Built-in role names cannot be redefined.

## Golem's own agents

When you turn on a feature that needs one, a Golem worker enrolls in your workspace as its own machine, with only the scopes that feature needs. The investigator's readers, threat intelligence, Golem's reviewer agent and the SIEM output each work this way. They appear in a read-only group marked **Managed by Golem** under **Hosts, Groups & Profiles**, and everything they do is signed into your record. To stop one, turn its feature off or revoke its host. See [Session review](/review).

## Revoking access

| To cut off | Do this | Takes effect |
|---|---|---|
| A person | Remove them under **Members** | Their next token request fails. A token they already hold lasts at most five more minutes. |
| A machine | Open it under **Hosts, Groups & Profiles** and choose **Revoke this host key** | At once for anything the machine signs; a token it holds lasts at most five more minutes. To come back, it must enroll again. |
| An enrollment key | Revoke it under **Settings → Deploy → Install** | No new machine can enroll with it, and no new headless agent can register with it |
| An agent registration | Not in the console yet; email [info@golem.team](mailto:info@golem.team) | It can no longer exchange its secret; a token it holds lasts at most five more minutes |

> [!WARNING]
> Revoking an enrollment key does not cut off the machines that already enrolled with it. They authenticate with their own keys. If a key leaked, revoke it, then revoke the host key of every machine you do not recognize.

## What it does not do

- Changes to roles, members and grants are not signed into the [record](/record). The record covers what agents did and the security decisions people made about it.
- Golem does not end a person's sign-in session elsewhere when you remove them; it stops issuing them tokens.
- Golem does not issue long-lived personal API tokens.