Autenticación
Cómo funcionan las API keys de Reclee, quién puede crearlas, cómo se revocan y qué hacer con un 401.
Toda llamada a la API REST y al servidor MCP se autentica con una API key en el header Authorization. No hay OAuth para la API REST ni scopes: la key actúa como la persona que la creó, en el workspace donde la creó.
curl https://app.reclee.com/api/v1/account/me \
-H "Authorization: Bearer rcl_..."Cómo es una key
- Empieza siempre con
rcl_, seguido de 43 caracteres aleatorios (256 bits). UnBearerque no empieza conrcl_se ignora y la llamada contesta401. - Va en el header
Authorization: Bearer <key>. Nunca en la URL ni en el cuerpo. - Reclee no guarda el secreto: guarda una huella (hash) que no se puede revertir. Por eso se muestra una sola vez, al crearla. Si lo pierdes, no hay forma de recuperarlo: revoca la key y crea otra.
- En las listas se reconoce por su nombre y su prefijo:
rcl_más los primeros 8 caracteres (rcl_Xk3f9Qa2). El prefijo sirve para distinguir una key de otra, no para usarla.
Dónde se crea
En la app, en Configuración → Developers → Crear una API key. El nombre es obligatorio (hasta 80 caracteres): una lista de keys sin nombre es una lista de la que nadie se anima a revocar nada.
Hay dos reglas:
- Solo se crea desde la app. La API no tiene una ruta para crear keys, y una key nunca puede crear otra: si pudiera, una key filtrada sobreviviría a su propia revocación.
- Hace falta asiento. Solo los roles Owner y Recruiter crean keys (ver Roles y asiento).
El servidor MCP también crea keys: cuando conectas un cliente MCP y autorizas el acceso, Reclee emite una key a tu nombre llamada <cliente> (MCP). Aparece en la misma lista y se revoca igual. Ver Autorización del MCP.
A quién pertenece una key
Una key está atada a una persona en un workspace (su membresía):
- Hereda el rol de esa persona. No tiene permisos propios ni scopes: lo que la persona puede hacer en la app, la key lo puede hacer por la API; lo que no, tampoco.
- Ve y escribe solo en ese workspace. Si trabajas en dos workspaces, necesitas una key en cada uno.
- Una persona puede tener varias keys en el mismo workspace (una por integración, por ejemplo). Todas comparten el mismo límite de pedidos, que es por persona.
- Todo lo que escribe queda registrado a nombre de esa persona, marcado como hecho por la API (o por el MCP).
Roles y asiento
Reclee tiene cuatro roles. Dos de ellos tienen asiento (son los que un plan pago cobra), y solo un asiento puede usar la API y el MCP:
| Rol | Asiento | ¿Crea keys? | ¿Su key funciona? |
|---|---|---|---|
OWNER | Sí | Sí | Sí |
RECRUITER | Sí | Sí | Sí |
COLLABORATOR | No | No | No |
VIEWER | No | No | No |
Dentro de lo que una key puede hacer, el rol sigue mandando: las rutas de facturación, miembros y configuración de la cuenta son solo para OWNER y con la key de un RECRUITER contestan 403 FORBIDDEN.
Lo que una key nunca puede hacer
Las operaciones que mueven dinero o cierran la cuenta exigen que el OWNER esté en persona en la app. Por API contestan siempre 403 FORBIDDEN, aunque la key sea de un OWNER:
| Operación | Rutas |
|---|---|
| Suscripción y plan | POST /billing/checkout, POST /billing/checkout/settle, POST /billing/trial, PUT y DELETE /billing/plan, GET /billing/plan/preview, PUT y DELETE /billing/cancellation |
| Comprar créditos | POST /billing/credits |
| Pagos y datos de facturación | POST /billing/portal, PUT /billing/profile |
| Propiedad del workspace | POST /account/members/{memberId}/ownership |
| Borrado del workspace | POST y DELETE /account/workspace/deletion, GET /account/workspace/deletion/preview |
| Contraseña | POST /account/me/password |
| API keys | Crear una key: no hay ruta; solo se crean desde la app. |
Estas rutas existen en la especificación para que el comportamiento sea explícito, pero están pensadas para la app.
Si a la persona le cambian el rol
El rol se lee en cada pedido, no queda congelado en la key:
- Si le bajan el rol a
COLLABORATORoVIEWER, su key no se revoca: queda dormida. Deja de resolver en el pedido siguiente (401) y, si más adelante le devuelven el asiento, vuelve a funcionar sola. En Configuración → Developers aparece como «Sin acceso» con el motivo. - Si la desactivan o sale del workspace, sus keys dejan de resolver.
- Si el workspace queda programado para borrarse, ninguna key del workspace resuelve.
- Si sube de
RECRUITERaOWNER(o al revés), la key gana o pierde en el acto el acceso a las rutas deOWNER.
Como una key dormida puede volver a funcionar, si la persona ya no debería tener acceso, revócala.
Listar y revocar
| Operación | Cómo |
|---|---|
| Ver las keys | Configuración → Developers, o GET /account/api-keys (paginada). Cada persona ve las suyas; un OWNER ve todas las del workspace, con su dueño y si hoy resuelven. |
| Revocar | El botón Revocar en la app, o POST /account/api-keys/{apiKeyId}/revoke. |
curl -X POST https://app.reclee.com/api/v1/account/api-keys/2a7d4c1b-9e3f-4b6a-8c5d-1e2f3a4b5c6d/revoke \
-H "Authorization: Bearer $RECLEE_API_KEY"Qué pasa al revocar:
- La key deja de funcionar en el pedido siguiente. No hay caché ni período de gracia.
- No se borra: queda en la lista marcada como revocada, con la fecha, para saber quién tuvo acceso y hasta cuándo.
- Es definitivo. Una key revocada no se reactiva; si hace falta, se crea una nueva.
- Revocar dos veces la misma key contesta igual que la primera.
- Puedes revocar tus propias keys aunque ya no tengas asiento: revocar es cómo se cierra una filtración, y no depende del rol. Un
OWNERpuede revocar cualquier key del workspace. - Revocar la key de un cliente MCP es también la forma de desconectarlo.
Cada key de la lista muestra cuándo se usó por última vez (se actualiza como mucho una vez por minuto). Una key que nadie usa hace meses es candidata a revocarse.
Errores 401
La API contesta un único 401 para cualquier problema de credencial, sin decir cuál fue:
{ "error": "UNAUTHENTICATED" }Las causas posibles:
| Causa | Qué hacer |
|---|---|
Falta el header Authorization o no dice Bearer. | Agrega Authorization: Bearer rcl_.... |
El token no empieza con rcl_ o está incompleto. | Copia la key completa, sin espacios ni saltos de línea. |
| La key fue revocada. | Crea una nueva. |
La persona perdió el asiento (pasó a COLLABORATOR o VIEWER). | Que un OWNER le devuelva el asiento, o usa la key de otra persona con asiento. |
| La persona fue desactivada, salió del workspace o nunca aceptó la invitación. | Usa la key de un miembro activo. |
| El workspace está programado para borrarse o fue desactivado. | Un OWNER puede cancelar el borrado desde la app. |
Un pedido con una key inválida no consume el límite de 60 pedidos por minuto de nadie. El MCP contesta el mismo 401, con el header WWW-Authenticate que le indica al cliente cómo volver a autorizar.
Distinto del 401 es el 403: la key es válida pero la operación no está permitida para tu rol (FORBIDDEN) o requiere asiento (SEAT_REQUIRED). Ver Errores.
Buenas prácticas de seguridad
- Una key por integración. Si se filtra la de un script, revocas esa y el resto sigue funcionando. El nombre debe decir dónde se usa.
- Nunca en el código ni en el repositorio. Usa variables de entorno o un gestor de secretos. Si una key llega a un commit, revócala aunque borres el commit.
- Solo desde el servidor. No pongas una key en una app web, móvil o en una extensión del navegador: cualquiera que la lea actúa como tú. La API REST no está pensada para llamarse desde el navegador.
- Con la persona correcta. La key hereda el rol de quien la crea: para una integración que solo lee vacantes, no uses la key de un
OWNER, que también puede tocar facturación y miembros. - Revisa la lista de vez en cuando. Revoca las keys que nadie usa y las de personas que ya no deberían tener acceso (recuerda que bajar el rol las deja dormidas, no revocadas).
- No la registres en logs. Si necesitas identificar una key en tus logs, usa su prefijo, nunca el secreto.
- Cita el
X-Request-Id. Toda respuesta trae ese header; si tienes que reportar un problema, ese id permite encontrar el pedido sin compartir la key.