# Autenticación

URL: https://wa.genuka.com/es/docs/authentication
Language: Spanish

> Claves API, alcance y buenas prácticas de rotación.

Cada solicitud se autentica con una clave API en el encabezado `Authorization`:

```http
Authorization: Bearer pk_live_...
```

> [!WARNING]
> **Nunca** manejas un token de Meta. Genuka WA guarda las credenciales de la Cloud API y las rota
> por ti: una sola clave API de Genuka basta, y solo da acceso a tus propios datos.

## Dos alcances de clave

| Alcance     | Acceso                       | Caso de uso                                            |
| ----------- | ---------------------------- | ------------------------------------------------------ |
| **Socio**   | Todos los clientes del socio | Una plataforma que gestiona números de varias empresas |
| **Cliente** | Una sola empresa             | Una empresa que integra únicamente sus propios números |

Una clave de cliente que intenta acceder a otra empresa recibe `403 out_of_scope`. Algunos endpoints
— facturación, uso del plan — exigen una clave de socio y, de lo contrario, responden
`403 partner_key_required`.

## Crear y revocar una clave

Las claves se gestionan desde el portal, en **Desarrolladores**. Una clave se muestra **una sola vez**
al crearla: Genuka solo almacena una huella y no puede volver a mostrártela.

Para rotar sin interrupción del servicio: crea la nueva clave, despliégala, confirma el tráfico en
los registros y luego revoca la anterior.

## Respuestas de error

| Estado | Código                 | Significado                              |
| ------ | ---------------------- | ---------------------------------------- |
| `401`  | `missing_bearer_token` | Falta el encabezado `Authorization`      |
| `401`  | `invalid_token`        | Clave desconocida o revocada             |
| `403`  | `out_of_scope`         | La clave está restringida a otra empresa |
| `403`  | `partner_key_required` | Endpoint reservado a las claves de socio |

## Seguridad

* Una clave API es un secreto del lado del servidor. Nunca la incluyas en un frontend ni en una
  aplicación móvil: cualquiera podría enviar mensajes en tu nombre y a tu costa.
* Usa claves distintas por entorno y por integración: así, revocar una se vuelve una operación
  quirúrgica en lugar de global.
* Cada solicitud queda registrada y es visible en el portal.
