Una guía de conocimiento: qué partes tiene un contrato OpenAPI 3 y cómo se declara en él una seguridad muy habitual en APIs empresariales: un token OAuth 2.0 Client Credentials obtenido con Client ID y Client Secret, más una API Key que identifica la suscripción del consumidor. El contrato completo y los comandos están también en el README.md de la izquierda.
¿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
componentsy$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
1. Entiende qué es un contrato y por qué escribirlo primero
OpenAPI es el estándar para describir una API REST en un archivo YAML o JSON: qué rutas tiene, qué recibe y devuelve cada una, qué errores da y cómo se autentica. Ese archivo es el contrato entre quien publica la API y quien la consume.
Escribirlo antes que el código (contract first) permite que frontend, backend y socios trabajen en paralelo, generar documentación y clientes automáticamente, validar las peticiones en el API Gateway y detectar cambios incompatibles antes de publicarlos.
2. Monta el esqueleto del documento
| Campo | Para qué sirve |
|---|---|
openapi | Versión de la especificación: 3.0.3 o 3.1.0. Obligatorio. |
info | Título, versión de la API, descripción y contacto. Obligatorio. |
servers | URL base de cada entorno (producción, preproducción…). |
paths | Las rutas y sus operaciones (GET, POST…), con parámetros, cuerpo y respuestas. |
components | Piezas reutilizables: esquemas de datos, parámetros, respuestas y esquemas de seguridad. |
security | La seguridad que se aplica por defecto a todas las operaciones. |
tags | Agrupan las operaciones en la documentación. |
El esqueleto mínimo de un contrato válido:
openapi: 3.0.3
info:
title: API de pedidos
version: 1.0.0
servers:
- url: https://api.ejemplo.com/pedidos/v1
paths: {}
components: {}
3. Describe las rutas y operaciones
Cada ruta de paths tiene sus operaciones (get, post…). Dale a cada una un operationId único (los generadores de código lo usan como nombre de método) y documenta todas sus respuestas:
paths:
/pedidos:
get:
tags: [Pedidos]
operationId: listarPedidos
summary: Lista los pedidos
responses:
'200':
description: Lista de pedidos
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pedido'
4. Reutiliza componentes
Todo lo que se repite se define una vez en components y se referencia con $ref. Si cambia el modelo de un pedido, cambia en todas las operaciones a la vez.
schemas: los modelos de datos (un pedido, un error), con tipos, campos obligatorios, formatos y ejemplos.parameters: parámetros comunes, como la paginación.responses: respuestas repetidas, como los errores 401 y 403.securitySchemes: los mecanismos de seguridad que usa la API.
5. Define los esquemas de seguridad
Primero se definen los mecanismos en components.securitySchemes: aquí, OAuth 2.0 con el flujo Client Credentials (con la URL del token y los scopes disponibles) y una API Key en una cabecera.
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)
6. Exige la seguridad: Y frente a O
Después se exigen con security: en la raíz del documento, para todas las operaciones, o en una operación concreta, que entonces sustituye a la de la raíz.
# 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: []
La forma de escribirla decide si hacen falta los dos mecanismos o basta con uno:
# 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: []
7. Entiende el flujo Client Credentials
Es el flujo de la comunicación entre aplicaciones, sin un usuario delante: un backend, un proceso batch o la plataforma de un socio. Cada aplicación consumidora se registra en el servidor de autorización y recibe dos datos:
- Client ID: identifica a la aplicación. No es secreto.
- Client Secret: demuestra que la aplicación es quien dice ser. Es una contraseña: nunca va en el código, en el contrato ni en el navegador; se guarda en un gestor de secretos (Azure Key Vault, por ejemplo) o en variables de entorno.
El funcionamiento:
- La aplicación pide un token a la
tokenUrlcon su Client ID, su Client Secret y los scopes que necesita. - El servidor de autorización comprueba las credenciales y devuelve un access token con caducidad (por ejemplo, una hora).
- La aplicación llama a la API con el token en
Authorization: Bearer …. - El API Gateway valida el token (firma, caducidad, audiencia y scopes) antes de dejar pasar la petición.
- Cuando el token caduca, la aplicación pide otro: este flujo no tiene refresh token.
La petición del token y su respuesta:
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
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
Con Microsoft Entra ID, por ejemplo, la tokenUrl es https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token y el scope se pide como api://{id-de-la-API}/.default.
8. Entiende qué aporta la API Key
La API Key identifica la suscripción del consumidor: sirve para aplicar cuotas y límites de peticiones, para la analítica de uso y para revocar el acceso a un consumidor concreto sin tocar el servidor de autorización. En Azure API Management, por ejemplo, es la clave de suscripción, que por defecto viaja en la cabecera Ocp-Apim-Subscription-Key.
Lo que no aporta es autenticación fuerte: es un valor fijo, no caduca sola y no lleva scopes. Por eso se combina con el token y no lo sustituye: el token dice quién es y qué puede hacer; la API Key, por qué suscripción entra y con qué cuota.
9. Documenta los errores 401 y 403
| Código | Significa | Ejemplo |
|---|---|---|
| 401 Unauthorized | No se sabe quién llama, o sus credenciales no valen. | Falta el token o la API Key, el token ha caducado o la firma no es válida. |
| 403 Forbidden | Se sabe quién llama, pero no tiene permiso para esa operación. | El token solo tiene pedidos.leer e intenta crear un pedido. |
Documentarlos en components.responses, con el mismo esquema de error, ayuda al consumidor a saber si debe pedir un token nuevo (401) o solicitar más permisos (403).
10. Revisa el contrato completo
Una API de pedidos que exige token y API Key en todas las operaciones, con un scope de lectura por defecto y uno de escritura para crear pedidos. Lo tienes también en el README.md de la izquierda:
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'
11. Llama a la API como lo haría un consumidor
Cada llamada lleva las dos cabeceras:
GET /pedidos/v1/pedidos HTTP/1.1
Host: api.ejemplo.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-API-Key: 3f9c1e...
Desde PowerShell, en Windows, guarda primero las credenciales en variables de entorno (nunca en el script):
$env:CLIENT_ID = "tu-client-id"
$env:CLIENT_SECRET = "tu-client-secret"
$env:API_KEY = "tu-api-key"
Y pide el token y llama a la API:
# 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
}
12. Valida el contrato
Guarda el contrato como openapi.yaml y valídalo con Redocly CLI (necesita Node.js). También puedes pegarlo en editor.swagger.io para verlo como documentación interactiva.
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.versiony la ruta/v1) y no publicar cambios incompatibles en la misma versión.