Empezar

Autenticación de la API

Una clave de API por integración, en la cabecera Authorization. La clave decide la organización y los scopes; nada más lo hace.

La cabecera

http

GET /api/v1/bookings HTTP/1.1
Host: wearetransfers.com
Authorization: Bearer wat_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Solo Bearer. La clave no se acepta en la URL, en el cuerpo ni en otra cabecera. Solo HTTPS.

Qué es una clave

Concepto	Qué es
Organización	Tu empresa en We Are Transfers. Toda clave pertenece a una y solo ve sus datos.
Integración	Un software conectado (ERP, PMS, CRM, facturación, flota, BI, automatización…). Tiene sus propios scopes y puede desactivarse sin tocar las demás.
Clave	Una credencial de una integración, con nombre, entorno, scopes ⊆ los de la integración y caducidad opcional. Se puede rotar y revocar. La tuya será `wat_live_`: no hay servidor de pruebas donde abra una `wat_test_` (Entornos).
Prefijo	Los primeros caracteres (`wat_live_` + 8) que se enseñan en el panel para reconocerla. El resto no se guarda: solo su hash.

Los scopes efectivos de una petición son la intersección de los de la clave y los de la integración. Si a la integración se le quita un scope, todas sus claves lo pierden al instante. GET /v1/integrations/me los enseña.

Qué se comprueba en cada petición

Forma de la clave y entorno: una wat_test_ contra este servidor es 401 wrong_environment, y no hay ningún otro servidor donde abra. Ver Entornos.
Que exista (por hash), no esté revocada ni caducada.
Que su integración esté activa y que la API esté activada para tu organización.
Que la clave tenga todos los scopes que pide el endpoint. Si no: 403 insufficient_scope con details.required_scope.
Los límites.

Códigos de autenticación

HTTP	code	Cuándo
401	`unauthorized`	Falta la cabecera Authorization o no es Bearer.
401	`invalid_key`	La clave no tiene la forma esperada o no existe.
401	`revoked_key`	Existió y se revocó (rotación o baja). Usa la nueva.
401	`expired_key`	Tenía fecha de caducidad y ha pasado.
401	`wrong_environment`	Clave de test contra live o al revés.
403	`integration_disabled`	La integración está desactivada o revocada.
403	`api_disabled`	La API no está activada para esta organización.
403	`insufficient_scope`	Falta un scope. details.required_scope dice cuál.
429	`rate_limited`	Demasiados fallos de autenticación desde tu IP (60 por minuto).

Rotación y revocación

Rotar crea una clave nueva con los mismos scopes y revoca la vieja en el mismo instante: no hay periodo de gracia. Cambia primero el secreto en tu sistema y rota después, o hazlo en una ventana sin tráfico. Una clave revocada responde revoked_key para siempre: no se reactiva.

Si una clave se filtra

Pide a We Are Transfers que la revoque (info@wearetransfers.com, desde la cuenta titular; hoy no se revoca desde el panel), que cree otra con los scopes mínimos, y revisa el registro de peticiones de la integración. Ver Seguridad.

Buenas prácticas

Una clave por sistema. No compartas la misma entre un ERP y un cuadro de mandos: si hay que revocar una, no cae la otra.
Pide los scopes mínimos. passengers:read y pricing:read solo si vas a usar esos datos.
Guarda la clave en un gestor de secretos; nunca en el repositorio ni en el navegador.
Registra el X-WAT-Request-Id de cada respuesta junto a tu propio log: es lo que soporte necesita.