/pom-ai-mcp/oauth/token: intercambio de token OAuth

Donde un código de autorización se convierte en un token de acceso, y donde se renuevan los tokens caducados. El cliente se encarga de ello; rara vez lo ves, salvo que algo falle.

https://example.com/pom-ai-mcp/oauth/token

POST únicamente. Cualquier otra cosa devuelve 405.

Dos tipos de concesión

authorization_code intercambia un código recién generado por tokens. El cliente envía el código, su ID de cliente, el URI de redirección que utilizó, el recurso y el code_verifier de PKCE.

refresh_token renueva un token de acceso a punto de caducar. El cliente envía el token de actualización, su ID de cliente y el recurso.

Cualquier otra cosa devuelve unsupported_grant_type.

Qué se devuelve

Un token de acceso, un token de actualización, token_type: Bearer y expires_in.

Un cliente actualiza en silencio. Cada renovación correcta inicia otra ventana de actualización de 30 días, de modo que la actividad normal no exige iniciar sesión periódicamente en el navegador. Treinta días sin renovación exigen autorizar de nuevo.

La renovación rota ambas credenciales una vez, a la vez que conserva la autorización original. El token de acceso antiguo deja de funcionar. Si se pierde la respuesta de la renovación, el mismo cliente puede repetir la misma solicitud de actualización durante 30 segundos y recibir el mismo par de reemplazo, con su vida útil de acceso restante. Esta recuperación no puede ampliar la autorización, cambiar los ámbitos, sobrevivir a una revocación ni devolver un par que ya haya sido sustituido por otra rotación. Las tareas pendientes, la propiedad de los resultados y las aprobaciones no caducadas siguen asociadas a la misma autorización; sus comprobaciones existentes de caducidad, revocación y capacidades siguen aplicándose.

Qué se comprueba

El intercambio es estricto, y cada comprobación corresponde a un fallo que podrías ver.

El recurso debe coincidir. Se compara con el endpoint MCP de este sitio por esquema, host, puerto y ruta. Una discordancia devuelve invalid_resource. Este es el fallo OAuth más común con diferencia, y casi siempre significa que la URL configurada del cliente difiere del endpoint: una variante de www, una ruta final sobrante o el sitio equivocado de una multisitio.

El cliente debe existir. Los ID de cliente desconocidos devuelven invalid_client. Después de un Reset OAuth, los clientes registrados previamente producen este error hasta que se vuelven a registrar.

El código debe ser válido. Debe existir, no haber sido utilizado, estar dentro de su vida de 10 minutos, pertenecer a este cliente, coincidir con el URI de redirección utilizado y coincidir con el recurso. De lo contrario, invalid_grant.

PKCE debe verificarse. El code_verifier debe generar mediante hash el desafío enviado en la autorización. De lo contrario, invalid_grant.

Un token de actualización debe estar vigente. No debe estar revocado ni caducado, debe pertenecer a este cliente y debe coincidir con el recurso.

Sin secreto de cliente

El endpoint utiliza token_endpoint_auth_method: none. Los clientes son públicos y no poseen ningún secreto, razón por la cual PKCE aporta la prueba de posesión.

Un cliente que intente autenticarse con un secreto no está haciendo nada útil; el servidor no espera ninguno.

Limitación de frecuencia

5 solicitudes por minuto por IP para este endpoint. El registro y la revocación tienen presupuestos separados. Las respuestas de cuota incluyen Retry-After; los fallos temporales del limitador devuelven HTTP 503 con temporarily_unavailable.

Un cliente que reintente un intercambio fallido en bucle chocará con 429. Al diagnosticar, cambia una sola cosa y prueba una vez en lugar de repetidamente; de lo contrario, el límite de frecuencia enmascarará si tu solución funcionó.

Los tokens están vinculados y cifrados con hash

Cada token está vinculado a su cliente, al ID de blog del sitio, al recurso, al usuario que aprueba y a los ámbitos aprobados. Los tokens se almacenan como hashes, nunca en texto plano.

Consecuencias que conviene conocer:

• un token de un sitio nunca funciona en otro;
• la actualización conserva los ámbitos originales, no los amplía;
• los tokens revocados y caducados se purgan automáticamente.

Requisitos

• OAuth activado, o el endpoint devuelve 404 con oauth_disabled.
• Enlaces permanentes bonitos, ya que la ruta es una regla de reescritura.

La forma localizada /es/pom-ai-mcp/oauth/token también se acepta donde POM Translate antepone prefijos a las URL.

En el registro

Los intercambios de código de autorización correctos identifican el tipo de concesión, el cliente y el usuario. Los intentos de actualización registran el éxito o el rechazo y el ID del cliente, sin credenciales. Una sucesión de entradas authorization_code para el mismo cliente sugiere que la actualización está fallando y que el cliente se vuelve a autorizar con más frecuencia de la que debería.

Cuando falla

Si el intercambio se realiza correctamente pero las llamadas MCP posteriores siguen devolviendo 401, comprueba que el cliente utiliza el token más reciente y el mismo recurso canónico. Comprueba también si la cabecera Authorization llega a WordPress; el diagnóstico del panel de ajustes de MCP informa de si llega.