> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/dcal/developers/api-keys.md).

# API keys

Create an API key so another system can check your dCal availability and create, list, reschedule or cancel bookings. Covers the key format, the scopes, how keys are stored and how to revoke one.

An API key lets another system, such as your own app, a CRM or an automation, use the [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md) or the [Cal.com-compatible API](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md) without signing in to the dashboard. A key works for your whole workspace, and its scopes decide what it may do. Keys are also one of the two ways to connect an AI assistant to dCal's MCP server at `https://mcp.dcal.ai/mcp`; the other is signing in. See [Connect an AI assistant (MCP)](https://docs.dapta.ai/dcal/developers/mcp-server.md).

> **⚠️ Note:** Only workspace **admins** and **owners** can create or revoke keys. Members do not see **API and webhooks** in the left menu, and a member who opens one of its pages sees **You don’t have access**.

***

## Create a key

**Step 1:** In the left menu, open **API and webhooks** > **API keys**, or go straight to [app.dcal.ai/admin/developers/keys](https://app.dcal.ai/admin/developers/keys). The page opens on the **API keys** section, with your keys.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-f49848500a68063dcd2fdef4f3f9ba25cae10d21%2Fdcal-api-keys-01-keys-section.png?alt=media" alt="The API keys section header, with its description and the Create key button boxed"><figcaption><p>The <strong>API keys</strong> page, under <strong>API and webhooks</strong>.</p></figcaption></figure>

***

**Step 2:** Click **Create key**, in the **API keys** header. Type a **Name** that says which system will use the key and what for, for example `Acme CRM sync`. The list shows each key's access later, but only the name tells you who uses it.

**Step 3:** Under **Access this key grants**, tick only what that system needs. Each line has a plain name and a **Read**, **Write** or **Destructive** label; [Scopes](#scopes) below gives the scope behind each name. **Check free times** is ticked for you.

**Step 4:** Optionally, under **Event types**, choose **Only these event types** and tick the ones the key may use. The list holds your own event types and every team's, with the team's name in parentheses. Then choose when the key **Expires**: **Never**, **In 30 days**, **In 90 days** or **In 365 days**. **Create key** stays disabled until the key has a name, at least one access and, with **Only these event types**, at least one event type.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-e0431ee9f702fc6a77a7d7e2d851164642cb351a%2Fdcal-api-keys-02-create-key-dialog.png?alt=media" alt="The Create key dialog with the name Acme CRM sync, the Access this key grants list boxed with Check free times and Create, hold, reschedule, confirm and decline bookings ticked, All event types ticked, and Expires boxed and set to Never"><figcaption><p>Give each key a name that says who uses it, and only the access it needs.</p></figcaption></figure>

***

**Step 5:** Click **Create key**. The key appears once, in a box above the list, under the line *Copy this now*. Copy it straight into the secret store of the system that will use it. Once you reload or leave the page, dCal cannot show it again.

> **⚠️ Note:** Treat a key like a password: anyone who holds it can act on your workspace within its scopes. Keep it on a server. Never put it in a web page, a mobile app, a spreadsheet or a URL.

***

**Step 6:** Send the key with every request in the `Authorization` header, as `Authorization: Bearer <your key>`. The [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md) page has complete examples.

***

## Key format

Every key has the same shape:

```
dcl_<prefix>_<secret>
```

The letters `dcl_`, an 8-character prefix, an underscore and a 32-character secret: 45 characters in all. The **API keys** list shows each key's name with its prefix and its last 4 characters, never the whole key, and the word **revoked** next to keys that no longer work. Under each active key it shows the key's access, **All event types** or how many event types it is limited to, its expiry (**No expiry**, or **Expires** with the date, in red once **Expired**), and **Last used** with the date, or **Never used**. Dates are in UTC, written as year, month and day.

***

## Scopes

| Scope               | Name in the dashboard                                      | What it allows                                                                                                                                                            | Endpoints                                                                                                                                                                                                                                                                             |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `availability:read` | **Check free times**                                       | Read the open times of an event. Over MCP, check attendee availability when the key also has `bookings:write` and no event-type limit.                                    | `GET /v1/machine/availability`, `GET /v2/slots`                                                                                                                                                                                                                                       |
| `bookings:read`     | **Read bookings**                                          | List and read the bookings of your workspace.                                                                                                                             | `GET /v1/machine/bookings`, `GET /v2/bookings/{uid}`                                                                                                                                                                                                                                  |
| `bookings:write`    | **Create, hold, reschedule, confirm and decline bookings** | Create and reschedule bookings, add a guest to a booking, and cancel through the REST endpoints. Over MCP, it also holds times and confirms or declines booking requests. | `POST /v1/machine/bookings`, `PATCH /v1/machine/bookings/{uid}`, `POST /v1/machine/bookings/{uid}/cancel`, `POST /v1/machine/bookings/{uid}/attendees`, `POST /v2/bookings`, `POST /v2/bookings/{uid}/reschedule`, `POST /v2/bookings/{uid}/cancel`, `POST /v2/bookings/{uid}/guests` |
| `bookings:cancel`   | **Cancel bookings**                                        | Cancel bookings. The cancel endpoints accept it or `bookings:write`.                                                                                                      | `POST /v1/machine/bookings/{uid}/cancel`, `POST /v2/bookings/{uid}/cancel`                                                                                                                                                                                                            |
| `event-types:read`  | **See event types**                                        | List your event types.                                                                                                                                                    | `GET /v2/event-types`                                                                                                                                                                                                                                                                 |
| `calendars:read`    | **See connected calendars**                                | List the calendars connected in your workspace and find open times across them.                                                                                           | `GET /v2/calendars`, `POST /v2/calendars/availability`                                                                                                                                                                                                                                |

When an AI assistant connects to dCal's MCP server with a key, the same scopes decide what it may do; the [MCP tools reference](https://docs.dapta.ai/dcal/developers/mcp-tools.md) lists the scope each tool needs. An assistant that connects by signing in has its owner's or admin's full access instead.

Common combinations:

* A booking assistant, a chatbot or your own booking form: **Check free times** and **Create, hold, reschedule, confirm and decline bookings**.
* A reporting or CRM sync that only reads: **Read bookings**.

A request made with a key that lacks the scope it needs is refused with `403` and the message `Missing scope: <scope>`, or `Missing scope: bookings:cancel or bookings:write` on the `/v1/machine` cancel endpoint.

***

## How keys are stored

* dCal keeps only a one-way hash (SHA-256) of each key, plus its prefix and last 4 characters. Nobody, at your company or at Dapta, can read a key back from dCal. If you lose one, create a new key and revoke the old one.
* A key belongs to the workspace, not to the person who created it. It keeps working if that person leaves the workspace, so revoke the keys you no longer use.
* A revoked key stops working at once.
* A key with an expiry date stops working at that moment, like a revoked one.

***

## Revoke a key

**Step 1:** On **API and webhooks** > **API keys**, click **Revoke** on the key's row.

**Step 2:** Confirm in the **Revoke this key?** dialog. It warns you that the key stops working immediately and that anything using it will start failing. dCal shows **Key revoked.** and the row stays in the list, marked **revoked**. There is no undo.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-ada1ee04cf19f7486e859ffd8b6a16be885c30ff%2Fdcal-api-keys-03-revoke-dialog.png?alt=media" alt="The Revoke this key? confirmation dialog naming the key Acme CRM sync, with the Cancel and Revoke buttons, Revoke boxed"><figcaption><p>The dialog names the key you are about to revoke. It cannot be undone.</p></figcaption></figure>

> **💡 Tip:** To rotate a key without downtime, create the new key first, switch your system over to it, then revoke the old one.

## Related

* [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md): the endpoints a key unlocks, with examples.
* [Cal.com-compatible API](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md): the `/v2` endpoints a key also unlocks.
* [Webhooks](https://docs.dapta.ai/dcal/integrations/webhooks.md): get booking changes pushed to you instead of asking for them.
* [Security and privacy](https://docs.dapta.ai/dcal/security-and-privacy.md): how keys, secrets and links are protected.
* [Members and roles](https://docs.dapta.ai/dcal/account/members-and-roles.md): who is an admin or an owner.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dapta.ai/dcal/developers/api-keys.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
