Reclee

Autorización OAuth

El flujo OAuth 2.1 del servidor MCP de punta a punta, para quien escribe su propio cliente.

Esta página es para quien implementa un cliente MCP propio. Si usas Claude, Claude Code, Cursor o el Inspector, el cliente hace todo esto solo: ve a Conectar un cliente.

Reclee implementa la autorización de MCP: OAuth 2.1 con descubrimiento (RFC 9728 y RFC 8414), registro dinámico de clientes (RFC 7591) y PKCE S256 obligatorio. Solo hay clientes públicos (sin client_secret) y un único grant: authorization_code. Todos los paths de esta página son relativos a https://app.reclee.com.

El token que se obtiene es una API key rcl_… del workspace que la persona eligió: no expira, no hay refresh_token y vive hasta que alguien la revoca.

El flujo completo

Descubrir. El cliente llama a POST /api/mcp sin credencial y recibe 401 con el header WWW-Authenticate, que apunta al documento del recurso protegido.

Leer los metadatos. GET /.well-known/oauth-protected-resource dice cuál es el servidor de autorización; GET /.well-known/oauth-authorization-server dice sus endpoints.

Registrarse. POST /oauth/register con el nombre y las redirect_uris devuelve un client_id.

Autorizar. El cliente abre el navegador en /oauth/authorize con su code_challenge. La persona inicia sesión, elige un workspace y acepta. Reclee redirige a la redirect_uri con un code.

Canjear. POST /oauth/token con el code y el code_verifier devuelve el access_token.

Usar. Cada POST /api/mcp lleva Authorization: Bearer rcl_….

Todos estos endpoints, salvo la página /oauth/authorize, contestan OPTIONS y mandan Access-Control-Allow-Origin: *: ninguno usa cookies, así que un cliente que corre en el navegador puede llamarlos.

1. El 401 que inicia el descubrimiento

POST/api/mcp

Sin Authorization, o con una key inválida, revocada o de alguien que ya no tiene asiento:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer resource_metadata="https://app.reclee.com/.well-known/oauth-protected-resource"

{ "error": "UNAUTHENTICATED" }

El cuerpo es el mismo que el de la API REST: no distingue entre una key que falta, una mal escrita o una revocada.

2. Los metadatos

GET/.well-known/oauth-protected-resource

También responde en /.well-known/oauth-protected-resource/api/mcp (la forma con sufijo de RFC 9728).

{
  "resource": "https://app.reclee.com/api/mcp",
  "authorization_servers": ["https://app.reclee.com"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Reclee"
}
GET/.well-known/oauth-authorization-server
{
  "issuer": "https://app.reclee.com",
  "authorization_endpoint": "https://app.reclee.com/oauth/authorize",
  "token_endpoint": "https://app.reclee.com/oauth/token",
  "registration_endpoint": "https://app.reclee.com/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"]
}

Los documentos se arman con el origen del request: el issuer coincide con la URL que usó el cliente.

3. Registrar el cliente

POST/oauth/register

Cuerpo JSON:

CampoTipoRequeridoDescripción
redirect_urisstring[]SíDe 1 a 10 direcciones, cada una de hasta 2000 caracteres. https con cualquier host; http solo en loopback (localhost, 127.0.0.1 o [::1]), con cualquier puerto. Sin fragmento (#), sin usuario en la URL y sin esquemas propios (miapp://).
client_namestringOpcionalDe 1 a 80 caracteres. Es lo que ve la persona en la pantalla de consentimiento y el nombre de la API key que se crea. Sin él, «MCP client».

Cualquier otro metadato de RFC 7591 (grant_types, token_endpoint_auth_method, scope…) se acepta y se ignora.

curl -s https://app.reclee.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Recruiting Agent",
    "redirect_uris": ["http://127.0.0.1:53682/callback"]
  }'

Respuesta 201 Created:

{
  "client_id": "6f1c2b9e-4d3a-4e8b-9a17-2c5d8e0f3b41",
  "client_name": "Acme Recruiting Agent",
  "redirect_uris": ["http://127.0.0.1:53682/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "client_id_issued_at": 1792857600
}
ErrorStatusCuándo
invalid_redirect_uri400Falta redirect_uris, está vacía o alguna dirección no cumple las reglas.
invalid_client_metadata400El cuerpo no es JSON, o client_name no cumple.
server_error500Se superó el tope de registros por minuto (por dirección de origen y global), o falló algo del lado de Reclee. Espera un minuto y reintenta.

Registra cuando vayas a autorizar

El registro es abierto y tiene tope por minuto. Un cliente que pasa más de un día sin canjear ningún código puede borrarse: registra justo antes de autorizar y guarda el client_id después de canjear el primer token.

4. Autorizar en el navegador

GET/oauth/authorize

El cliente abre esta URL en el navegador de la persona. No es una API: es la pantalla de consentimiento de Reclee.

CampoTipoRequeridoDescripción
response_typestringSíSiempre code.
client_iduuidSíEl que devolvió el registro.
redirect_uristringSíUna de las registradas, exactamente igual.
code_challengestringSíBASE64URL(SHA-256(code_verifier)), sin relleno: 43 caracteres.
code_challenge_methodstringSíSiempre S256. plain no se acepta.
statestringOpcionalHasta 2000 caracteres. Vuelve tal cual en la redirección; úsalo contra CSRF.

scope y resource se aceptan y se ignoran: no hay scopes, la key hereda el rol de la persona. Un parámetro repetido cuenta como inválido.

https://app.reclee.com/oauth/authorize?response_type=code
  &client_id=6f1c2b9e-4d3a-4e8b-9a17-2c5d8e0f3b41
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj

La pantalla de consentimiento

Si la persona no tiene sesión iniciada, Reclee la lleva a iniciar sesión y la devuelve a esta pantalla. Ahí ve:

  • El nombre del cliente, con la advertencia de que Reclee no lo verifica.
  • A qué dirección vuelve al aceptar: el host de la redirect_uri, o «una app en esta computadora» si es loopback.
  • Sus workspaces, con su rol en cada uno. Solo puede elegir uno donde tiene asiento (OWNER o RECRUITER); los demás aparecen deshabilitados con el motivo. Si no tiene asiento en ninguno, solo puede cancelar.

Cómo vuelve al cliente

Qué pasóRedirección
La persona aceptaredirect_uri?code=…&state=…
La persona cancelaredirect_uri?error=access_denied&state=…
response_type distinto de coderedirect_uri?error=unsupported_response_type&state=…
Falta o es inválido code_challenge, el método no es S256, state es demasiado largo o hay un parámetro repetidoredirect_uri?error=invalid_request
client_id desconocido o redirect_uri no registradaNo redirige. Muestra un error en pantalla, porque la dirección no es de confianza.

Si la redirect_uri ya traía query propia, Reclee agrega code y state a continuación sin tocarla.

El code vale 60 segundos y se usa una sola vez.

5. Canjear el código

POST/oauth/token

Acepta application/x-www-form-urlencoded (lo que pide RFC 6749) o application/json.

CampoTipoRequeridoDescripción
grant_typestringSíSiempre authorization_code.
codestringSíEl que llegó a la redirect_uri.
redirect_uristringSíLa misma que se usó en /oauth/authorize.
client_iduuidSíEl del registro.
code_verifierstringSíDe 43 a 128 caracteres de [A-Za-z0-9._~-].
curl -s https://app.reclee.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=SplxlOBeZQQYbYS6WxSbIA2nqzJr8Vq4tRk3mX9wYcE \
  -d redirect_uri=http://127.0.0.1:53682/callback \
  -d client_id=6f1c2b9e-4d3a-4e8b-9a17-2c5d8e0f3b41 \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Respuesta 200, con Cache-Control: no-store:

{
  "access_token": "rcl_Qm9vdHN0cmFwLWV4YW1wbGUta2V5LW5vdC1yZWFsLTAx",
  "token_type": "Bearer"
}

No hay expires_in, refresh_token ni scope. En la app, la key aparece en Configuración → Developers con el nombre del cliente seguido de «(MCP)».

ErrorStatusCuándo
invalid_request400Falta un campo, tiene mal formato, viene repetido, o el cuerpo no es form ni JSON.
unsupported_grant_type400grant_type no es authorization_code (por ejemplo, refresh_token).
invalid_client401client_id falta o no es un UUID.
invalid_grant400El código no existe, ya se usó, venció, no corresponde a ese client_id o redirect_uri, el code_verifier no coincide con el code_challenge, o la persona perdió el asiento o el acceso al workspace entre la autorización y el canje.
server_error500Falló algo del lado de Reclee.

Los errores siguen RFC 6749 §5.2: { "error": "invalid_grant" }.

Un código presentado dos veces revoca su key

Si un código ya canjeado vuelve a llegar a /oauth/token, la respuesta es invalid_grant y además se revoca la API key que ese código había emitido. Es la defensa de RFC 6749 contra un código robado: canjea cada código una sola vez.

Generar el PKCE

code_verifier=$(openssl rand 32 | base64 | tr '+/' '-_' | tr -d '=\n')
code_challenge=$(printf '%s' "$code_verifier" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=\n')
echo "$code_verifier $code_challenge"

Usar el token

curl -s https://app.reclee.com/api/mcp \
  -H "Authorization: Bearer rcl_Qm9vdHN0cmFwLWV4YW1wbGUta2V5LW5vdC1yZWFsLTAx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

El mismo token sirve para la API REST: es una API key como cualquier otra.

Cuándo deja de funcionar

El token no expira por tiempo. Deja de funcionar, y el servidor contesta 401 con el WWW-Authenticate del paso 1, cuando:

  • alguien lo revoca;
  • la persona pierde el asiento (pasa a Colaborador o Lector) o deja de ser miembro activo del workspace;
  • el workspace se desactiva o tiene la baja programada.

Si a la persona le devuelven el asiento, la misma key vuelve a funcionar. Ante un 401, tu cliente tiene que repetir la autorización: no hay refresh.

Desconectar un cliente

Desconectar es revocar su API key:

  • En la app: Configuración → Developers, la key con el nombre del cliente seguido de «(MCP)» → revocar. Cada persona revoca las suyas; un Dueño puede revocar cualquiera del workspace.
  • Por API: POST /api/v1/account/api-keys/{apiKeyId}/revoke (el id sale de GET /api/v1/account/api-keys).

La key deja de funcionar en el próximo request. Queda en la lista marcada como revocada, para saber quién tuvo acceso y hasta cuándo, y no se puede reactivar.

En esta página