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

# Authentication

> Authenticate Zeeg API requests with Bearer tokens. Learn how to generate API keys, scope them to specific permissions, and keep your credentials secure.

All Zeeg API endpoints require authentication via a Bearer token sent in the `Authorization` header.

## Generating a Token

Create an API token from your Zeeg dashboard:

**[Account Settings > API](https://app.zeeg.me/account/settings/api-access)**

When creating a token, you select the specific scopes it should have access to. Follow the principle of least privilege — only grant the scopes your integration actually needs.

## Making Authenticated Requests

Include your token in the `Authorization` header of every request. We also recommend setting `Accept: application/json`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.zeeg.me/v2/scheduled-events \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.zeeg.me/v2/scheduled-events",
      headers={
          "Authorization": "Bearer YOUR_TOKEN",
          "Accept": "application/json",
      },
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.zeeg.me/v2/scheduled-events", {
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      Accept: "application/json",
    },
  });
  ```
</CodeGroup>

If the token is missing or invalid, the API returns a `401 Unauthorized` response.

## Token Scopes

Each token is scoped to specific permissions. The table below lists all available scopes and the endpoints they unlock.

| Scope                  | Description                            | Endpoints                                                             |
| ---------------------- | -------------------------------------- | --------------------------------------------------------------------- |
| `events:read`          | Read scheduled events                  | List events, get event details                                        |
| `events:write`         | Cancel or hand over events             | Cancel event, cancel invitee, hand over event                         |
| `schedules:read`       | Read availability schedules            | List schedules, get schedule by UUID, get default schedule            |
| `schedules:write`      | Update availability schedules          | Update schedule by UUID, update default schedule                      |
| `timetable`            | Access availability and time slot data | Get available time slots                                              |
| `booking`              | Create events programmatically         | Create an event via the API                                           |
| `webhooks:read`        | Read webhook subscriptions             | List webhooks, get webhook details                                    |
| `webhooks:write`       | Create and delete webhooks             | Create webhook, delete webhook                                        |
| `users:read`           | List workspace users                   | List users in a workspace, check logged-in user                       |
| `teams:write`          | Add team members                       | Add a team member to a workspace                                      |
| `outbound-calls:write` | Trigger AI agent calls                 | Create outbound call                                                  |
| `notes:read`           | Read notes on scheduled events         | List notes by event, get note details                                 |
| `notes:write`          | Create, update, and delete notes       | Create note, update note, delete note                                 |
| `admin:full`           | Full organization access               | Required for org-wide operations (e.g., listing all workspace events) |

<Note>
  The `timetable` and `booking` scopes require a paid Zeeg subscription. If your plan does not include API access to availability slots or programmatic booking, requests using these scopes will be rejected.
</Note>

## Scope Requirements by Endpoint Group

| Endpoint Group                                     | Required Scope         |
| -------------------------------------------------- | ---------------------- |
| Scheduled Events (read)                            | `events:read`          |
| Scheduled Events (cancel/handover)                 | `events:write`         |
| Scheduling Pages (list/get/toggle/single-use link) | `events:read`          |
| Available Time Slots                               | `timetable`            |
| Create an Event                                    | `booking`              |
| Availability Schedules (read)                      | `schedules:read`       |
| Availability Schedules (update)                    | `schedules:write`      |
| Webhooks (read)                                    | `webhooks:read`        |
| Webhooks (create/delete)                           | `webhooks:write`       |
| Workspace Users                                    | `users:read`           |
| Add Team Member                                    | `teams:write`          |
| AI Agent Outbound Call                             | `outbound-calls:write` |
| Notes (read)                                       | `notes:read`           |
| Notes (create/update/delete)                       | `notes:write`          |
| Organization-wide Operations                       | `admin:full`           |

<Warning>
  **Keep your API tokens secure.** Treat them like passwords. Do not commit tokens to version control, expose them in client-side code, or share them in plain text. If a token is compromised, revoke it immediately from the [API settings page](https://app.zeeg.me/account/settings/api-access) and generate a new one.
</Warning>