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

# Autenticación

> Cada solicitud lleva una clave de API Bearer. La clave determina el entorno y contiene los alcances (scopes) que tiene su app.

Cada solicitud a la Developer API lleva una clave de API `Bearer` en el encabezado `Authorization`:

```bash
# Sandbox
curl https://api.staging.maple.inc/v1/me \
  -H "Authorization: Bearer mpk_test_..."
```

Una clave responde tres preguntas a la vez: **qué app** es usted, **a qué entorno** pertenece (sandbox o producción) y **qué alcances** tiene. Verifique cualquier clave con `GET /v1/me`, que devuelve exactamente eso.

Cada entorno tiene su propia URL base: `https://api.staging.maple.inc/v1` para el sandbox y `https://api.maple.inc/v1` para producción. Use la clave que corresponda al host. Vea [Entornos](https://docs.maple.inc/es/developer-api/concepts/environments.md).

## Claves de API

Maple aprueba su app y el límite máximo de sus alcances. Los miembros invitados de la organización crean y revocan claves en **Developers → su app → Overview & keys**. Inicie sesión en el panel del entorno de la clave (`https://app.staging.maple.inc` para claves de sandbox, `https://app.maple.inc` para claves de producción); no se requiere seleccionar un comercio ni un restaurante.

| Clave        | Entorno    | URL base                           |
| ------------ | ---------- | ---------------------------------- |
| `mpk_test_…` | Sandbox    | `https://api.staging.maple.inc/v1` |
| `mpk_live_…` | Producción | `https://api.maple.inc/v1`         |

Envíe la clave como token bearer en cada solicitud, dirigida a la URL base de su entorno. Mantenga las claves en el servidor; nunca las incluya en una app cliente ni las suba al control de versiones. Reducir los alcances de una app surte efecto de inmediato en sus claves existentes.

> [!WARNING]
>
> **La clave completa se muestra una sola vez.** Guárdela en su administrador de secretos antes de cerrar el cuadro de diálogo de creación. La lista de claves muestra metadatos y los últimos cuatro caracteres, no un secreto recuperable. Mantenga las claves fuera de registros, capturas de pantalla y mensajes de soporte.

Para reemplazar una clave, cree una nueva, actualice su cliente, verifique que funcione y revoque explícitamente la clave anterior. La revocación detiene de inmediato la autenticación con esa clave. Una app suspendida o revocada no puede autenticarse con ninguna de sus claves, aunque la consola sigue permitiendo la inspección y la revocación preventiva.

Una clave **no** otorga acceso a locales, no crea un sandbox ni aprueba el uso en producción. Maple administra por separado la titularidad de la app, los límites máximos de alcances, los accesos otorgados a locales y la aprobación de producción. El acceso del personal por sí solo no otorga acceso a una app no vinculada en la consola de desarrolladores.

Siga la [Guía de inicio rápido](https://docs.maple.inc/es/developer-api/quickstart.md) para crear una clave y verificar con `/v1/me` la app y el entorno devueltos.

## Alcances

El acceso se limita por alcances, de modo que su app solo tiene los permisos que necesita:

| Alcance                                        | Otorga                                                                                                                                                        |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locations:read`                               | Listar y leer los locales con acceso otorgado                                                                                                                 |
| `connections:read` / `connections:write`       | Leer o administrar la conexión del local                                                                                                                      |
| `orders:read` / `orders:write`                 | Leer pedidos o enviar decisiones sobre pedidos                                                                                                                |
| `menus:read` / `menus:write`                   | Leer o publicar el menú de un local                                                                                                                           |
| `delivery_zones:read` / `delivery_zones:write` | Leer o administrar las zonas de entrega de un local conectado y verificar la cobertura de entrega                                                             |
| `webhooks:read` / `webhooks:write`             | Leer o administrar suscripciones a webhooks                                                                                                                   |
| `bookings:read`                                | Leer reservas, perfil, disponibilidad, configuración y el plano de sala en vivo de los locales con acceso otorgado                                            |
| `bookings:write`                               | Retener horarios y crear, modificar o cancelar reservas para los clientes                                                                                     |
| `bookings:manage`                              | Actuar en nombre del establecimiento: confirmar, rechazar, sentar, completar, cancelar o marcar reservas como no presentadas, y sentar a clientes sin reserva |
| `bookings:configure`                           | Publicar la configuración de reservas nativa                                                                                                                  |

Una solicitud a la que le falta un alcance requerido devuelve `403` con el código `insufficient_scope`. Una clave usada en el entorno equivocado devuelve `403` con el código `wrong_environment`. Vea [Errores](https://docs.maple.inc/es/developer-api/concepts/errors.md).

> [!TIP]
>
> Verifique qué puede hacer una clave sin hacer una llamada real: `GET /v1/me` devuelve la app, su entorno y sus alcances efectivos.

## OAuth

> [!NOTE]
>
> **En construcción.** El acceso basado en OAuth (tokens delegados por el comercio y concesiones `client_credentials`) todavía no forma parte de la Developer API de disponibilidad general. Por ahora, use claves de API. Si su integración necesita OAuth, hable con el equipo de Maple; esta sección se ampliará cuando el flujo esté definido.