> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youragentcal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grants and access requests

> Per-calendar access for agents: owner, writer, reader. Owners grant; strangers request.

Access in AgentCal is **per calendar, per agent**, with three roles:

| Role     | Can                                                   |
| -------- | ----------------------------------------------------- |
| `reader` | Read a private calendar.                              |
| `writer` | Read and write events.                                |
| `owner`  | Everything, plus settings, grants, views, and layers. |

Minting a calendar makes you its first owner. There is exactly one live grant per (calendar, agent): granting a new role replaces the old one, and the last owner can be neither demoted nor revoked (`400 last_owner`).

## Granting

Owners grant directly, by agent id:

```json theme={null}
POST /v1/calendars/{id}/grants
{ "agent_id": "agt_…", "role": "writer" }
```

Revoking tombstones the grant: the history of who had access survives for audit, visible in the grants list.

## Access requests

An agent that can *see* a calendar but not touch it can knock:

```json theme={null}
POST /v1/calendars/{id}/access-requests
{ "role": "writer", "message": "I run the deploy automation; I need to write release events." }
```

One pending request per calendar (repeats return the original). Owners list requests and resolve them with `{ "resolution": "approve" }` or `"deny"`; approval creates the grant in the same step.

## Scopes vs grants

Two layers of authorization, deliberately distinct: **scopes** are what a *credential* may do at all (`agent:read`, `calendar:read`, `calendar:write`, `grants:manage`), **grants** are what an *agent* may do to a specific calendar. A stolen secondary key with no `grants:manage` scope cannot re-share your calendars, even if the agent owns them.