:::endpoint GET /v1/me/calendar/calendars

The first thing an app asks for, because everything else is keyed on a calendar:
appointments are drawn in these colours and a new one has to land in one of
these.

An account that has never opened a calendar gets its personal one made here, and
so does the workspace's own calendar, so this always returns at least two rows.

## Request

```bash
curl https://api.proppertrading.com/v1/me/calendar/calendars \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f"
```

## Response

```json
{
    "data": [
        {
            "id": "cal_r4d8h2m6t9w3k7nb",
            "object": "calendar",
            "name": "Sarah Klein",
            "color": "blue",
            "timezone": "Europe/Amsterdam",
            "is_team": false,
            "is_global": false,
            "is_primary": true,
            "is_mine": true,
            "owner": null,
            "access": "manage",
            "is_subscription": false,
            "channel": "private-calendar.cal_r4d8h2m6t9w3k7nb"
        },
        {
            "id": "cal_x5p9c3j7v2g6q4sa",
            "object": "calendar",
            "name": "Support",
            "color": "pink",
            "timezone": "Europe/Amsterdam",
            "is_team": true,
            "is_global": false,
            "is_primary": false,
            "is_mine": false,
            "owner": null,
            "access": "write",
            "is_subscription": false,
            "channel": "private-calendar.cal_x5p9c3j7v2g6q4sa"
        }
    ],
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}
```

| Field        | Description                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`         | The calendar, such as `cal_r4d8h2m6t9w3k7nb`. What `calendar_id` on an appointment and `calendars[]` on [the list](/docs/api/calendar/events) refer to |
| `is_team`    | A calendar of the whole firm rather than of one person. Everybody who may open the calendar at all can read it                             |
| `is_global`  | The one calendar of the workspace itself. Everybody has it, it is always there, and only an account that may manage calendars writes in it |
| `is_primary` | The one appointments land in when nothing says otherwise                                                                                   |
| `is_mine`    | Yours, as opposed to a colleague's or the team's                                                                                           |
| `owner`      | The colleague it belongs to, and null on your own and on the team's                                                                        |
| `access`     | `busy`, `read`, `write` or `manage`. See [the overview](/docs/api/calendar/overview) for what each one hands over                          |
| `is_subscription` | A copy of a calendar published elsewhere, such as a Google calendar followed from its address. Nobody writes in it, whatever `access` says: creating, changing, answering or deleting an appointment in it returns `calendar_read_only` |
| `channel`    | The [socket channel](/docs/api/apps/realtime) that says when anything in it changes, such as `private-calendar.cal_r4d8h2m6t9w3k7nb`. Subscribe to it as it is rather than building it from `id` |

## Errors

| Status | Code                     | Meaning                                    |
| ------ | ------------------------ | ------------------------------------------ |
| 403    | `insufficient_scope`     | This device does not hold `calendar:read`  |
| 403    | `calendar_not_permitted` | The account may not open a calendar at all |