Intercambio de Tokens (RFC 8693)

Intercambia un token de acceso válido por uno nuevo vinculado a una audiencia diferente o un conjunto de scopes reducido, sin cambiar el propietario del recurso.

El grant de intercambio de tokens (RFC 8693) permite que un cliente confidencial registrado — típicamente una pasarela o proxy — intercambie un token de acceso entrante por uno nuevo adecuado para un recurso de destino específico. Este es el mecanismo estándar para la delegación entre servicios y es necesario cuando un proxy debe llamar a una API de destino en nombre del propietario original del token.

Cuándo usar esto

Usa el intercambio de tokens cuando un servicio que recibe un Bearer token necesita llamar a una API de destino con una audiencia diferente, o necesita reducir el conjunto de scopes antes de reenviar. El propietario del recurso original (sub) siempre se preserva — el nuevo token permanece asociado al mismo usuario y tienda, solo con una audiencia diferente y/o menos scopes.

No uses esto para elevar privilegios. Solicitar un scope que no estaba en el token original siempre es rechazado.

Endpoint

POST https://app.whatalo.com/oauth/token
Content-Type: application/x-www-form-urlencoded

Parámetros

Todos los parámetros se envían como application/x-www-form-urlencoded.

Parámetro	Obligatorio	Descripción
`grant_type`	Sí	Debe ser `urn:ietf:params:oauth:grant-type:token-exchange`
`subject_token`	Sí	El token que se intercambia (el Bearer token entrante)
`subject_token_type`	Sí	Debe ser `urn:ietf:params:oauth:token-type:access_token`
`resource`	Recomendado	URI de audiencia de destino para el nuevo token (RFC 8707)
`audience`	Opcional	Alternativa a `resource`. Cuando ambos están presentes, `resource` tiene prioridad
`scope`	Opcional	Subconjunto de los scopes del token original separados por espacio. Si se omite, se heredan todos los scopes
`client_id`	Sí	Identificador público de tu cliente
`client_secret`	Sí	Secreto de tu cliente (mediante HTTP Basic o en el cuerpo)

Autenticación del cliente

El intercambio de tokens requiere autenticación de cliente confidencial. Los clientes públicos (token_endpoint_auth_method: "none") no están autorizados para usar este grant.

Autentica usando HTTP Basic (recomendado):

Authorization: Basic BASE64(client_id:client_secret)

O mediante parámetros en el cuerpo:

client_id=tu_client_id&client_secret=tu_client_secret

Requisitos de autorización

Tu cliente debe estar habilitado explícitamente para el intercambio de tokens por un administrador de Whatalo. Esto se controla mediante una configuración interna en el registro de tu cliente. Contacta con soporte para solicitar esta capacidad.

Además, si solicitas una resource (audiencia) diferente a la audiencia original del token, esa audiencia específica debe estar incluida en la lista de audiencias permitidas de tu cliente. Puedes siempre solicitar la misma audiencia que el token original (operación de reducción de scopes únicamente) sin necesidad de una entrada adicional en la lista.

Ejemplo de solicitud

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(tu_client_id:tu_client_secret)

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&subject_token=<token_de_acceso_entrante>
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
&resource=https%3A%2F%2Fapi.whatalo.com
&scope=read%3Astore+read%3Aproducts

Respuesta

Un intercambio exitoso retorna HTTP 200 con este cuerpo:

{
  "access_token": "nuevo_valor_de_token_opaco",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:store read:products"
}

No se emite refresh_token para grants de intercambio de tokens en la versión actual. El token de acceso retornado tiene una vigencia de 1 hora. Realiza un nuevo intercambio usando el flujo original si necesitas un token después del vencimiento.

Respuestas de error

Código de error	Estado HTTP	Cuándo ocurre
`invalid_request`	400	Falta `subject_token` o `subject_token_type`, o tiene un valor incorrecto
`invalid_client`	401	La autenticación del cliente falló o un cliente público intentó el intercambio
`invalid_grant`	400	El `subject_token` es desconocido, ha expirado o fue revocado
`unauthorized_client`	400	El cliente no tiene habilitada la capacidad de intercambio de tokens
`invalid_target`	400	La `resource`/`audience` solicitada no está permitida para este cliente
`invalid_scope`	400	El `scope` solicitado excede los scopes del token original

Notas de seguridad

Sin escalada de scopes. Solo puedes solicitar scopes que ya están presentes en el token original. Solicitar acceso más amplio siempre es rechazado con invalid_scope.
Propietario del recurso preservado. La reclamación sub (el usuario) del nuevo token siempre es la misma que en el token original. Este grant no cambia la propiedad.
Identidad del solicitante registrada. El client_id del nuevo token es tu cliente (el que realiza el intercambio), no el cliente original que obtuvo el token. Esto hace que la delegación sea auditable.
La audiencia debe estar explícitamente permitida. Solicitar una audiencia que no está en la lista permitida de tu cliente es rechazada con invalid_target (RFC 8707 §2.2), evitando la reutilización no autorizada de tokens entre recursos.

Anuncio en well-known

El Servidor de Autorización anuncia soporte para este grant en su documento de descubrimiento:

{
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:token-exchange"
  ]
}

Consulta la página de Descubrimiento para el documento de metadatos completo.

On this page