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

# Autenticación

> Bearer tokens, API keys vs OAuth, y cómo funciona el scoping por organización.

Toda petición debe llevar un bearer token en el header `Authorization`:

```http theme={null}
Authorization: Bearer fe_k_<hex_aleatorio>
```

FlowEstate acepta dos tipos de bearer:

| Tipo                   | Formato                          | Cuándo usarlo                                                                                |
| ---------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
| **API key**            | `fe_k_` + 32 caracteres hex      | Integraciones servidor-a-servidor, scripts, autenticación "API Key" en Make/Zapier           |
| **OAuth access token** | Token opaco, sin prefijo `fe_k_` | Integraciones del usuario final conectadas vía la app oficial de FlowEstate en Zapier / Make |

## API keys

Las API keys se crean en el panel de FlowEstate en **Configuración → API Keys**. La key cruda se muestra **una sola vez** al crearla; FlowEstate solo guarda un hash SHA-256. Si la pierdes, revócala y crea una nueva.

Cada key lleva:

* Un **set de scopes** que limita lo que puede hacer (ver [Scopes](/es/scopes)).
* Una **vinculación a una organización** — todas las lecturas y escrituras quedan automáticamente acotadas a esa organización.
* Una **fecha de expiración** opcional.
* Un **flag de activa** — desactivar una key sin borrarla revoca acceso al instante.

No hay un parámetro `organizationId` que pasar en ningún endpoint. El token es la fuente de verdad.

## OAuth access tokens

Si eres un usuario final conectando FlowEstate vía la app oficial de Zapier o Make, tu bearer es un access token OAuth emitido por el proveedor de identidad de FlowEstate. Normalmente no ves este token directamente — el conector lo maneja por ti.

Los tokens OAuth se comportan igual que las API keys desde la perspectiva del API: mismos scopes, mismo scoping por organización, mismos rate limits. Las diferencias son operativas:

* Están atados a un **usuario** específico, no a la organización en general.
* Expiran y se refrescan automáticamente.
* Se pueden revocar desde **Configuración → Apps Conectadas**.

## Errores de autenticación

| HTTP  | Código         | Cuándo                                                                                                     |
| ----- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| `401` | `UNAUTHORIZED` | Header `Authorization` ausente o mal formado, key desconocida, token OAuth expirado.                       |
| `403` | `FORBIDDEN`    | Key inactiva, expirada o sin un scope requerido; cliente OAuth deshabilitado o sin organización vinculada. |

Para troubleshootear, llama `GET /api/v1/me` con el mismo bearer — si eso devuelve `200`, tu autenticación está bien y el problema es aguas abajo (scopes, límites de plan, validación). Si `/me` falla, arregla la autenticación primero.

## Buenas prácticas

* **Una key por integración**, nombrada por la integración (`make-lead-ingest`, `zapier-pipeline-sync`). Más fácil de auditar y revocar.
* **Scopes mínimos.** No le des `leads:write` a una key que solo lee.
* **Rota periódicamente** — al menos cuando un empleado se va o cambias de plataforma de terceros.
* **Nunca commitees keys al repo.** Trátalas como contraseñas.
* **Usa expiraciones** para integraciones de corto plazo (backfills puntuales, trabajo de contratistas).