# Employee identity over MCP (pii:read)
URL: https://docs.autociso.io/release-notes/2026-09-mcp-employee-identity/
Description: A new Owner-granted API-token scope, pii:read, unlocks the employee_resolve MCP tool — real names and emails for explicit employee IDs, audited on every call. Every token creation and revocation is now in the audit trail too.

## Employee identity over MCP (`pii:read`)

**Plans:** every plan (the Audit Trail page needs a plan that includes it; the entries are readable over MCP with `audit_trail_search` on every plan).
**Where:** **user menu → API Tokens**; the `/mcp` endpoint

MCP results have always masked employee names and emails and returned the opaque `employeeId` as a join key. Integrations that need to act on a finding — email a manager, open a ticket for a person — had no sanctioned way to turn that ID back into a name. Now they do, on an opt-in credential that an Owner grants deliberately.

### What's new

#### A new scope: Employee identity (`pii:read`)

In **user menu → API Tokens → Create Token**, an organisation **Owner** can now select **Employee identity (pii:read)**. The dialog shows a warning, requires an expiry of at most **90 days** (**Never** and **1 year** are disabled; **90 days** is preselected) and asks you to confirm **Grant employee identity access?** before the token is created. Tokens carrying the scope show a **PII** tag in the list. A Manager can still create every other kind of token, and can still revoke a `pii:read` token.

#### One new tool: `employee_resolve`

A token with `pii:read` sees one extra tool, `employee_resolve(employeeIds[])`, which returns `{ employeeId, name, email }` for up to 50 IDs per call and lists unknown IDs explicitly. It is rate-limited per token, exists only for tokens with the scope (for everyone else it is unregistered, not merely hidden), and every call is written to your audit trail — the token and the IDs requested, never the names — before the result is returned. Everything else on MCP is exactly as masked as before. See [About `pii:read`](https://docs.autociso.io/developers/mcp/authentication/#pii-read) and the [guide](https://docs.autociso.io/developers/employee-identity/).

#### Token creation and revocation are on the audit trail

Every API token creation and revocation — any scope — now writes an `api_token.created` / `api_token.revoked` entry (HIGH for `pii:read`, MEDIUM otherwise) to the hash-chained audit trail, so a grant and its use sit in the same ledger.

#### Expiry rotation cues

The token list now shows **Expires in N days** once a token is within 14 days of expiry. `supplier_template:write` tokens, which already required an expiry, no longer offer **Never** in the dialog.

### Rollout

The scope is enabled per deployment. Where it is not yet enabled, the option is shown disabled in the console and the API answers `422 SCOPE_UNAVAILABLE`; nothing can be minted by accident. If it is switched off later, existing `pii:read` tokens stay valid but the tool disappears and no new grants are possible.

### For SDK users

Both SDKs learned the tool-plane `RATE_LIMITED` code: a non-retryable `ToolError` carrying `retryAfterSeconds` (`retry_after_seconds` in Python). The SDK does not retry it for you. See [MCP Errors and Retries](https://docs.autociso.io/developers/mcp/errors/).