# Contrato OpenAPI 3 con OAuth 2.0 Client Credentials y API Key

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/contrato-openapi-3-oauth-client-credentials-api-key/

## ¿Qué vas a aprender?

- Qué partes tiene un contrato OpenAPI 3 y para qué sirve cada una.
- Cómo reutilizar modelos, parámetros y respuestas con `components` y `$ref`.
- Cómo se declara la seguridad: definir los esquemas y exigirlos, y la diferencia entre Y y O.
- Cómo funciona OAuth 2.0 Client Credentials con **Client ID y Client Secret**.
- Qué aporta una **API Key** y por qué se combina con el token en vez de sustituirlo.
- Cómo pide el token y llama a la API un consumidor, y cómo validar el contrato.

## Requisitos previos

- Conocer lo básico de HTTP y REST: métodos, cabeceras, códigos de estado y JSON.
- Un editor con soporte de YAML, por ejemplo Visual Studio Code con una extensión de OpenAPI.
- **Node.js**, solo para validar el contrato en el último paso (opcional).
- Para probar de verdad: acceso a un servidor de autorización (por ejemplo, Microsoft Entra ID) con una aplicación registrada (opcional).

## Paso a paso

### Estructura del documento

| Campo | Para qué sirve |
|---|---|
| openapi | Versión (3.0.3 o 3.1.0). Obligatorio |
| info | Título, versión, descripción y contacto. Obligatorio |
| servers | URL base de cada entorno |
| paths | Rutas y operaciones |
| components | Esquemas, parámetros, respuestas y seguridad reutilizables |
| security | Seguridad por defecto |
| tags | Agrupación en la documentación |

### Esquemas de seguridad

```yaml
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Client Credentials (aplicación a aplicación)
      flows:
        clientCredentials:
          tokenUrl: https://login.ejemplo.com/oauth2/token
          scopes:
            pedidos.leer: Consultar pedidos
            pedidos.escribir: Crear pedidos
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Identifica la suscripción del consumidor (cuotas y analítica)
```

### Exigir la seguridad (Y frente a O)

```yaml
# En la raíz: todas las operaciones piden token Y API Key
security:
  - oauth2: [pedidos.leer]
    apiKey: []

paths:
  /pedidos:
    post:
      # En una operación: sustituye a la de la raíz (hay que repetir la API Key)
      security:
        - oauth2: [pedidos.escribir]
          apiKey: []
```

```yaml
# Y: token Y API Key (las dos en el mismo elemento de la lista)
security:
  - oauth2: [pedidos.leer]
    apiKey: []

# O: token O API Key (cada una en su propio elemento de la lista)
security:
  - oauth2: [pedidos.leer]
  - apiKey: []
```

### Client Credentials: pedir el token

```http
POST /oauth2/token HTTP/1.1
Host: login.ejemplo.com
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=pedidos.leer
```

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### Llamada a la API

```http
GET /pedidos/v1/pedidos HTTP/1.1
Host: api.ejemplo.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-API-Key: 3f9c1e...
```

Desde PowerShell:

```powershell
$env:CLIENT_ID     = "tu-client-id"
$env:CLIENT_SECRET = "tu-client-secret"
$env:API_KEY       = "tu-api-key"

# 1. Pedir el token con el Client ID y el Client Secret
$token = Invoke-RestMethod -Method Post -Uri "https://login.ejemplo.com/oauth2/token" `
  -ContentType "application/x-www-form-urlencoded" `
  -Body @{
    grant_type    = "client_credentials"
    client_id     = $env:CLIENT_ID
    client_secret = $env:CLIENT_SECRET
    scope         = "pedidos.leer"
  }

# 2. Llamar a la API con el token y la API Key
Invoke-RestMethod -Uri "https://api.ejemplo.com/pedidos/v1/pedidos" -Headers @{
  Authorization = "Bearer $($token.access_token)"
  "X-API-Key"   = $env:API_KEY
}
```

### Errores 401 y 403

- 401: falta el token o la API Key, o no son válidos
- 403: el token es válido pero no tiene el scope necesario

### Contrato completo (openapi.yaml)

```yaml
openapi: 3.0.3
info:
  title: API de pedidos
  version: 1.0.0
  description: >
    Consulta y alta de pedidos. Cada petición necesita un token OAuth 2.0
    (Client Credentials) y la API Key de la suscripción del consumidor.
  contact:
    name: Equipo de integración
    email: integracion@ejemplo.com
servers:
  - url: https://api.ejemplo.com/pedidos/v1
    description: Producción
  - url: https://api-pre.ejemplo.com/pedidos/v1
    description: Preproducción

tags:
  - name: Pedidos

security:
  - oauth2: [pedidos.leer]
    apiKey: []

paths:
  /pedidos:
    get:
      tags: [Pedidos]
      operationId: listarPedidos
      summary: Lista los pedidos
      parameters:
        - $ref: '#/components/parameters/Pagina'
      responses:
        '200':
          description: Lista de pedidos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pedido'
        '401':
          $ref: '#/components/responses/NoAutenticado'
        '403':
          $ref: '#/components/responses/SinPermiso'
    post:
      tags: [Pedidos]
      operationId: crearPedido
      summary: Crea un pedido
      security:
        - oauth2: [pedidos.escribir]
          apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PedidoNuevo'
      responses:
        '201':
          description: Pedido creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pedido'
        '400':
          $ref: '#/components/responses/Invalido'
        '401':
          $ref: '#/components/responses/NoAutenticado'
        '403':
          $ref: '#/components/responses/SinPermiso'
  /pedidos/{pedidoId}:
    get:
      tags: [Pedidos]
      operationId: leerPedido
      summary: Consulta un pedido
      parameters:
        - name: pedidoId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: El pedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pedido'
        '401':
          $ref: '#/components/responses/NoAutenticado'
        '404':
          description: No existe un pedido con ese identificador

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://login.ejemplo.com/oauth2/token
          scopes:
            pedidos.leer: Consultar pedidos
            pedidos.escribir: Crear pedidos
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

  parameters:
    Pagina:
      name: pagina
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1

  schemas:
    PedidoNuevo:
      type: object
      required: [cliente, importe]
      properties:
        cliente:
          type: string
          example: CLI-0042
        importe:
          type: number
          format: double
          minimum: 0
          example: 129.90
    Pedido:
      allOf:
        - $ref: '#/components/schemas/PedidoNuevo'
        - type: object
          required: [id, estado]
          properties:
            id:
              type: string
              example: PED-2026-0001
            estado:
              type: string
              enum: [pendiente, enviado, entregado]
    Error:
      type: object
      required: [codigo, mensaje]
      properties:
        codigo:
          type: string
        mensaje:
          type: string

  responses:
    Invalido:
      description: La petición no cumple el contrato
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NoAutenticado:
      description: Falta el token o la API Key, o no son válidos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SinPermiso:
      description: El token es válido pero no tiene el scope necesario
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
```

### Validar el contrato

```bash
npx @redocly/cli lint openapi.yaml
```

## Errores habituales

- **Se exige un mecanismo cuando querías los dos (o al revés)**: En `security`, dos esquemas en el **mismo** elemento de la lista significan Y; en elementos **distintos**, O. Revisa los guiones del paso 6.
- **Una operación deja de pedir la API Key**: El `security` de una operación sustituye por completo al de la raíz. Si en la operación solo pones `oauth2`, la API Key deja de exigirse: repite los dos esquemas.
- **La API queda abierta sin querer**: `security: []` en una operación quita toda la seguridad. Úsalo solo a propósito, por ejemplo en un endpoint de salud.
- **Secretos dentro del contrato**: El contrato se comparte y se publica: nunca lleva Client Secret ni API Keys reales, solo la `tokenUrl` y los scopes.
- **Se pide un scope que no está declarado**: Todo scope usado en `security` tiene que existir en `flows.clientCredentials.scopes`; si no, los validadores dan error y el gateway puede rechazar el token.
- **Error al pedir el token en Microsoft Entra ID**: En Client Credentials, Entra ID solo acepta scopes del tipo `api://{id-de-la-API}/.default`: los permisos concretos se conceden a la aplicación como roles, no se piden uno a uno.
- **Se pide un token en cada llamada**: Sobrecarga el servidor de autorización y añade latencia. Guarda el token y reutilízalo hasta poco antes de que caduque (`expires_in`).
- **La API Key viaja en la URL**: Como parámetro de consulta (`?api_key=…`) acaba en los logs de proxies y servidores. Envíala siempre en una cabecera.
- **Se confunden 401 y 403**: Si un token válido sin el scope necesario devuelve 401, el consumidor pedirá un token nuevo una y otra vez sin resolver nada. Falta de permiso es 403.

## Siguientes pasos

- Importar el contrato en el API Gateway (por ejemplo, Azure API Management) y validar el token con su política `validate-jwt`.
- Generar clientes y stubs de servidor a partir del contrato con OpenAPI Generator.
- Levantar un servidor simulado (mock) con Prism para que los consumidores prueben antes de que exista el backend.
- Añadir la validación del contrato y la detección de cambios incompatibles al pipeline de CI/CD.
- Versionar el contrato (`info.version` y la ruta `/v1`) y no publicar cambios incompatibles en la misma versión.
