OAuth

Gestión del flujo OAuth PKCE para conectar cuentas de MercadoPago.

Flujo completo

sequenceDiagram
    participant Admin
    participant API as Integration API
    participant DB as D1
    participant MP as MercadoPago

    Admin->>API: GET /oauth/login?client=mi-cliente
    API->>DB: Verificar API key activa del cliente
    API->>DB: Verificar no tenga token activo
    API->>DB: Guardar state + code_verifier
    API-->>Admin: 302 Redirect → auth.mercadopago.com

    Note over Admin,MP: El usuario autoriza en MercadoPago

    MP->>API: GET /oauth/callback?code=XXX&state=YYY
    API->>DB: Buscar state, obtener code_verifier
    API->>MP: POST /oauth/token (code + code_verifier)
    MP-->>API: access_token, refresh_token
    API->>DB: Upsert token
    API-->>MP: 200 OK

Endpoints

GET /oauth/login

Inicia el flujo OAuth. Redirige al usuario a MercadoPago.

Query parameters:

Validaciones:

• El cliente debe tener API key activa
• El cliente no debe tener un token OAuth vigente (409 si ya está autenticado)

GET /oauth/login?client=mi-cliente

302 Redirect → https://auth.mercadopago.com/authorization?...

GET /oauth/callback

Callback que MercadoPago llama después de la autorización.

GET /oauth/validate

Valida si una API key o admin token es válida.

curl https://api.example.com/oauth/validate \
  -H "x-api-token: mk_mi_key"

{ "valid": true, "type": "admin", "client": null }

{ "valid": true, "type": "client", "client": "mi-cliente" }

GET /oauth/status

Estado de autenticación del cliente.

curl https://api.example.com/oauth/status \
  -H "x-api-token: mk_client_key"

{
  "authenticated": true,
  "client": "mi-cliente",
  "mp_user_id": 241983636,
  "live_mode": true,
  "expires_at": "2025-08-10T14:26:42.000Z",
  "expires_in_hours": 4320.5,
  "expired": false
}

POST /oauth/refresh

Renueva el access_token usando el refresh_token.

curl -X POST https://api.example.com/oauth/refresh \
  -H "x-api-token: mk_client_key"

{
  "message": "Token refreshed successfully",
  "clientName": "mi-cliente",
  "expiresAt": "2025-08-15T14:26:42.000Z"
}

POST /oauth/logout

Elimina el token OAuth del cliente.

curl -X POST https://api.example.com/oauth/logout \
  -H "x-api-token: mk_client_key"

{ "message": "Session closed for 'mi-cliente'" }