> 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/dapta-docs-es/dcal/developers/api-keys.md).

# Claves de API

Crea una clave de API para que otro sistema consulte tu disponibilidad en dCal y cree, liste, reprograme o cancele reservas. Incluye el formato de la clave, los permisos, cómo se guardan las claves y

Una clave de API permite que otro sistema, como tu propia app, un CRM o una automatización, use la [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md) o la [API compatible con Cal.com](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md) sin iniciar sesión en el panel. Una clave sirve para todo tu workspace, y sus permisos deciden qué puede hacer. Las claves también son una de las dos formas de conectar un asistente de IA al servidor MCP de dCal en `https://mcp.dcal.ai/mcp`; la otra es iniciar sesión. Mira [Conecta un asistente de IA (MCP)](https://docs.dapta.ai/dapta-docs-es/dcal/developers/mcp-server.md).

> **⚠️ Nota:** Solo los **administradores** y **propietarios** del workspace pueden crear o revocar claves. Los miembros no ven **API y webhooks** en el menú de la izquierda, y un miembro que abre una de sus páginas ve **No tienes acceso**.

***

## Crear una clave

**Paso 1:** En el menú de la izquierda, abre **API y webhooks** > **Claves API**, o ve directo a [app.dcal.ai/admin/developers/keys](https://app.dcal.ai/admin/developers/keys). La página abre en la sección **Claves API**, con tus claves.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-fcee65e304081b1aa586d9774ac7650cf38373f3%2Fdcal-api-keys-01-keys-section.png?alt=media" alt="El encabezado de la sección Claves API, con su descripción y el botón Crear clave marcado"><figcaption><p>La página <strong>Claves API</strong>, dentro de <strong>API y webhooks</strong>.</p></figcaption></figure>

***

**Paso 2:** Haz clic en **Crear clave**, en el encabezado de **Claves API**. Escribe un **Nombre** que diga qué sistema va a usar la clave y para qué, por ejemplo `Sincronización CRM Acme`. Después la lista muestra el acceso de cada clave, pero solo el nombre te dice quién la usa.

**Paso 3:** En **Acceso que da esta clave**, marca solo lo que ese sistema necesita. Cada línea tiene un nombre sencillo y una etiqueta **Lectura**, **Escritura** o **Destructiva**; [Permisos](#permisos), más abajo, da el permiso que hay detrás de cada nombre. **Consultar horarios libres** viene marcado.

**Paso 4:** Si quieres, en **Tipos de evento** elige **Solo estos tipos de evento** y marca los que la clave puede usar. La lista trae tus propios tipos de evento y los de cada equipo, con el nombre del equipo entre paréntesis. Luego elige cuándo **Vence** la clave: **Nunca**, **En 30 días**, **En 90 días** o **En 365 días**. **Crear clave** sigue desactivado hasta que la clave tenga un nombre, al menos un acceso y, con **Solo estos tipos de evento**, al menos un tipo de evento.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-43cf8d7e5603027bbbe644aa310c48acdd4617f1%2Fdcal-api-keys-02-create-key-dialog.png?alt=media" alt="El diálogo Crear clave con el nombre Sincronización CRM Acme, la lista Acceso que da esta clave en un recuadro con Consultar horarios libres y Crear, apartar, reagendar, confirmar y rechazar reservas marcados, Todos los tipos de evento marcado, y Vence en un recuadro con la opción Nunca"><figcaption><p>Ponle a cada clave un nombre que diga quién la usa, y solo el acceso que necesita.</p></figcaption></figure>

***

**Paso 5:** Haz clic en **Crear clave**. La clave aparece una sola vez, en un recuadro encima de la lista, bajo la línea *Cópiala ahora*. Cópiala directo en el almacén de secretos del sistema que la va a usar. En cuanto recargues o salgas de la página, dCal no puede volver a mostrarla.

> **⚠️ Nota:** Trata una clave como una contraseña: quien la tenga puede actuar sobre tu workspace dentro de sus permisos. Guárdala en un servidor. Nunca la pongas en una página web, una app móvil, una hoja de cálculo ni una URL.

***

**Paso 6:** Envía la clave en cada petición, en la cabecera `Authorization`, como `Authorization: Bearer <tu clave>`. La página [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md) tiene ejemplos completos.

***

## Formato de la clave

Todas las claves tienen la misma forma:

```
dcl_<prefijo>_<secreto>
```

Las letras `dcl_`, un prefijo de 8 caracteres, un guion bajo y un secreto de 32 caracteres: 45 caracteres en total. La lista **Claves API** muestra el nombre de cada clave con su prefijo y sus 4 últimos caracteres, nunca la clave completa, y la palabra **revocada** junto a las claves que ya no funcionan. Debajo de cada clave activa muestra su acceso, **Todos los tipos de evento** o a cuántos tipos de evento está limitada, su vencimiento (**Sin vencimiento**, o **Vence el** con la fecha, en rojo cuando ya **Venció**), y **Último uso** con la fecha, o **Sin usar**. Las fechas están en UTC y se escriben como año, mes y día.

***

## Permisos

| Permiso             | Nombre en el panel                                           | Qué permite                                                                                                                                                                     | Endpoints                                                                                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `availability:read` | **Consultar horarios libres**                                | Leer los horarios libres de un evento. Por MCP, consultar la disponibilidad de asistentes si la clave también tiene `bookings:write` y no está limitada a tipos de evento.      | `GET /v1/machine/availability`, `GET /v2/slots`                                                                                                                                                                                                                                       |
| `bookings:read`     | **Leer reservas**                                            | Listar y leer las reservas de tu workspace.                                                                                                                                     | `GET /v1/machine/bookings`, `GET /v2/bookings/{uid}`                                                                                                                                                                                                                                  |
| `bookings:write`    | **Crear, apartar, reagendar, confirmar y rechazar reservas** | Crear y reprogramar reservas, añadir un invitado a una reserva, y cancelar por los endpoints REST. Por MCP, además aparta horarios y confirma o rechaza solicitudes de reserva. | `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`   | **Cancelar reservas**                                        | Cancelar reservas. Los endpoints de cancelación aceptan este permiso o `bookings:write`.                                                                                        | `POST /v1/machine/bookings/{uid}/cancel`, `POST /v2/bookings/{uid}/cancel`                                                                                                                                                                                                            |
| `event-types:read`  | **Ver tipos de evento**                                      | Listar tus tipos de evento.                                                                                                                                                     | `GET /v2/event-types`                                                                                                                                                                                                                                                                 |
| `calendars:read`    | **Ver calendarios conectados**                               | Listar los calendarios conectados en tu workspace y buscar horarios libres en ellos.                                                                                            | `GET /v2/calendars`, `POST /v2/calendars/availability`                                                                                                                                                                                                                                |

Cuando un asistente de IA se conecta al servidor MCP de dCal con una clave, los mismos permisos deciden qué puede hacer; la [Referencia de herramientas MCP](https://docs.dapta.ai/dapta-docs-es/dcal/developers/mcp-tools.md) indica el permiso que necesita cada herramienta. Un asistente que se conecta iniciando sesión tiene, en cambio, todo el acceso de su propietario o administrador.

Combinaciones habituales:

* Un asistente de reservas, un chatbot o tu propio formulario de reserva: **Consultar horarios libres** y **Crear, apartar, reagendar, confirmar y rechazar reservas**.
* Una sincronización de reportes o de CRM que solo lee: **Leer reservas**.

Una petición hecha con una clave a la que le falta el permiso necesario se rechaza con `403` y el mensaje `Missing scope: <permiso>`, o `Missing scope: bookings:cancel or bookings:write` en el endpoint de cancelación de `/v1/machine`.

***

## Cómo se guardan las claves

* dCal solo guarda un hash de un solo sentido (SHA-256) de cada clave, más su prefijo y sus 4 últimos caracteres. Nadie, ni en tu empresa ni en Dapta, puede leer una clave desde dCal. Si pierdes una, crea una clave nueva y revoca la anterior.
* Una clave pertenece al workspace, no a la persona que la creó. Sigue funcionando si esa persona sale del workspace, así que revoca las claves que ya no uses.
* Una clave revocada deja de funcionar en el acto.
* Una clave con fecha de vencimiento deja de funcionar en ese momento, igual que una revocada.

***

## Revocar una clave

**Paso 1:** En **API y webhooks** > **Claves API**, haz clic en **Revocar** en la fila de la clave.

**Paso 2:** Confirma en el diálogo **¿Revocar esta clave?**. Te avisa de que la clave dejará de funcionar de inmediato y de que lo que la use empezará a fallar. dCal muestra **Clave revocada.** y la fila sigue en la lista, marcada como **revocada**. No se puede deshacer.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-b91d4e3ba43ef977af579449185944b807fff04c%2Fdcal-api-keys-03-revoke-dialog.png?alt=media" alt="El diálogo de confirmación ¿Revocar esta clave? con el nombre de la clave Sincronización CRM Acme y los botones Cancelar y Revocar, Revocar marcado"><figcaption><p>El diálogo nombra la clave que vas a revocar. No se puede deshacer.</p></figcaption></figure>

> **💡 Tip:** Para cambiar una clave sin cortar el servicio, crea primero la nueva, pasa tu sistema a ella y después revoca la anterior.

## Relacionado

* [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md): los endpoints que abre una clave, con ejemplos.
* [API compatible con Cal.com](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md): los endpoints `/v2` que una clave también abre.
* [Webhooks](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks.md): recibe los cambios de las reservas en lugar de preguntar por ellos.
* [Seguridad y privacidad](https://docs.dapta.ai/dapta-docs-es/dcal/security-and-privacy.md): cómo se protegen las claves, los secretos y los enlaces.
* [Miembros y roles](https://docs.dapta.ai/dapta-docs-es/dcal/account/members-and-roles.md): quién es administrador o propietario.


---

# 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/dapta-docs-es/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.
