# Manage your team from your agent

Org admin tokens, the team tools of zn-gate mcp, and how a person approves every change that an agent proposes.

Source: https://usezn.com/docs/team/agents/

Team lets an owner or admin read the organization and propose changes from a coding agent such as Claude Code or Codex: list members, check the audit log, revoke a lost laptop or tighten the policy. The agent never applies a change on its own. Every write becomes a pending change that a person approves outside the conversation.

zn-gate is a local guardrail, not an MDM. Org admin tokens give an agent a narrow, revocable way to help you administer the organization; they do not give the organization control over anyone's machine.

## Create an org admin token

1. In the dashboard, open **Team → Agent tokens**.
2. Give the token a name (for example `laptop-claude`), pick its scopes and an expiry of 7, 30 or 90 days.
3. Copy the token. **It is shown once.** zn stores only a hash of it, so it cannot be shown again; if you lose it, revoke it and create a new one.

Tokens start with `znorg_`, so secret scanners and the zn-gate Scrubber can recognize them. The part after `znorg_` up to the next `_` is the public prefix shown in the dashboard and in the activity log.

Limits:

- Up to 10 active tokens per organization and 5 per person.
- A token works only while its creator is still an owner or admin. If they leave the organization or become a member, the token stops working at once and shows as **Inactive**.
- Revoking a token takes effect on the next request and cancels its pending changes. Owners and admins can revoke any token of the organization.

## Scopes

New tokens start with the read scopes ticked. Add write scopes only if you want the agent to propose changes.

| Scope | Lets the token |
|---|---|
| `org:read` | See the organization (name, plan, seats, policy version), its installations and pending changes |
| `members:read` | See members and pending invitations |
| `members:write` | Propose inviting a member, revoking an invitation, removing a member, demoting an admin or revoking an installation |
| `policy:read` | See the current policy and its history |
| `policy:publish` | Propose policy changes |
| `audit:read` | Query the zn-gate audit log, its summary and the organization activity |
| `audit:export` | Download audit exports (CSV or JSON) to a local file |

A token inherits the limits of its creator: an admin's token cannot remove another admin or change roles, because admins cannot do that either. Auditors can create tokens limited to `audit:read` and `audit:export`.

No token, whatever its scopes, can:

- touch billing, seats or the subscription;
- create, list or revoke tokens, or change organization settings;
- create join tokens or accept invitations;
- approve or reject a pending change, including its own.

## Connect your agent

Run these commands in your own terminal, not through the agent.

```bash
# 1. Copy the token, then store it in the system keychain (read from the clipboard)
npx -y zn-gate team admin login --from-clipboard

# 2a. Claude Code
claude mcp add zn-gate -- npx -y zn-gate mcp
```

For Codex, add the server to `~/.codex/config.toml`:

```toml
[mcp_servers.zn-gate]
command = "npx"
args = ["-y", "zn-gate", "mcp"]
```

`zn-gate team admin login` checks the token with the API and keeps it in the macOS Keychain, Windows Credential Manager or libsecret, out of the agent configuration. `zn-gate team admin status` shows which organization and token are configured (never the secret), and `zn-gate team admin logout` removes it from the machine. Revoke the token in the dashboard as well if the machine is lost.

The `team_*` tools appear in the agent only when a token is configured, and only those allowed by its scopes. `ZN_LOCAL_ONLY=true` turns them off.

### CI and machines without a keychain

Set `ZN_ORG_TOKEN` as a CI secret or in your shell. Do not put it in the agent's MCP configuration (`.mcp.json`, `~/.codex/config.toml`): the agent can read those files.

```bash
export ZN_ORG_TOKEN=<paste the token here>
```

## What the agent can do

Read tools: `team_whoami`, `team_org_get`, `team_members_list`, `team_installs_list`, `team_policy_get`, `team_audit_query`, `team_audit_summary`, `team_activity_list`, `team_changes_list` and `team_change_status`. `team_audit_export` writes the export to `~/zn-exports/` and returns only its path, row count and SHA-256, never the content.

Write tools propose a change and return its status: `team_member_invite`, `team_invitation_revoke`, `team_member_remove`, `team_member_set_role`, `team_install_revoke`, `team_policy_propose` and `team_change_cancel`. The token never appears in tool results, errors or logs; only its prefix does.

## How approvals work

Every write is stored on the server as a pending change with a summary and an 8-character digest, both computed by the server from the parameters. The server also decides the class of the change; whatever the agent sends is ignored.

**Changes that tighten access or can be undone** (removing a member, revoking an invitation or an installation, demoting an admin, inviting a member, adding a deny rule, removing allowed hosts) are confirmed by a person, in this order:

1. a confirmation form shown by the agent, if the client supports MCP elicitation forms;
2. otherwise a native system dialog, where **No** is the default and no answer in 2 minutes counts as no;
3. otherwise a link to **Team → Approvals** in the dashboard.

The confirmation in the agent must happen within 10 minutes. The dashboard link stays valid for 72 hours.

**Changes that open access or grant privileges** (adding allowed hosts or commands, removing or reordering rules, inviting an admin or promoting someone to admin) are approved only in the dashboard, within 72 hours. Approving requires a sign-in from the last 10 minutes; if your session is older, the dashboard asks you to sign in again. Granting the admin role can only be approved by the owner. When the organization uses **Always approve in the dashboard**, the same recent sign-in is required for every change proposed by an agent.

The approval page shows the server summary, the digest, which token and client asked for it, and for policy changes the rules before and after. A note written by the agent is shown last and marked as unverified. Only approve changes you asked for, and check that the digest matches the one your agent shows.

The server checks everything again when the change is applied: the creator's role, the scopes, the organization setting and the policy version. If the policy changed in the meantime, the change fails and the agent has to propose it again.

## Organization setting: agent changes

In **Team → Settings**, the owner chooses how agent changes are approved:

| Mode | Effect |
|---|---|
| Confirm in the agent (default) | As described above |
| Always approve in the dashboard | Every change proposed by a token waits for an owner or admin in the dashboard |
| Read only | Tokens can only read; proposals are refused |

## Activity log

**Team → Activity** lists every request made with an org token, reads included, and every change made in the dashboard. Each entry shows who acted, whether it came from the dashboard or **via agent**, the token prefix and id, the client (for example `claude-code 2.1.240`), the action and its result, including refused requests. IP addresses are not stored. Open it from a token's row to see only that token.

## Remote MCP server (coming soon)

A hosted MCP server at `https://mcp.usezn.com/mcp`, with sign-in through your zn account, is planned for a later release. It will offer the same tools, and every write will be approved in the dashboard.

## Limits

- Someone who steals a token can, until it expires or is revoked, at most make changes of the first kind: they tighten access or can be undone from the dashboard, and they appear in the activity log. They cannot open the policy, grant the admin role, touch billing or create tokens. Choose **Always approve in the dashboard** if you want every change to go through a signed-in session.
- A confirmation in the agent or in a system dialog protects against a prompt injection that tries to approve on its own. It does not protect against software on the machine that can control the user interface.
- Approval only helps if the person reads what they approve. The summary and the digest come from the server, never from the agent.