Todas las guías
  1. Inicio
  2. Guías técnicas
  3. APIs

APIsNivel intermedio

Contrato OpenAPI 3 con OAuth 2.0 Client Credentials y API Key

9 min de lectura

Todas las guías

Contrato OpenAPI 3 con OAuth 2.0 Client Credentials y API Key

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 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

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

CampoPara qué sirve
openapiVersión de la especificación: 3.0.3 o 3.1.0. Obligatorio.
infoTítulo, versión de la API, descripción y contacto. Obligatorio.
serversURL base de cada entorno (producción, preproducción…).
pathsLas rutas y sus operaciones (GET, POST…), con parámetros, cuerpo y respuestas.
componentsPiezas reutilizables: esquemas de datos, parámetros, respuestas y esquemas de seguridad.
securityLa seguridad que se aplica por defecto a todas las operaciones.
tagsAgrupan 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:

  1. La aplicación pide un token a la tokenUrl con su Client ID, su Client Secret y los scopes que necesita.
  2. El servidor de autorización comprueba las credenciales y devuelve un access token con caducidad (por ejemplo, una hora).
  3. La aplicación llama a la API con el token en Authorization: Bearer ….
  4. El API Gateway valida el token (firma, caducidad, audiencia y scopes) antes de dejar pasar la petición.
  5. 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ódigoSignificaEjemplo
401 UnauthorizedNo 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 ForbiddenSe 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.version y la ruta /v1) y no publicar cambios incompatibles en la misma versión.

Compartir

Más guías sobre

Ver todas las guías

Otras guías técnicas

Ver todas las guías

APIsIntermedio

Estructura básica de una API en IBM API Connect 10

Cómo se estructura una API en IBM API Connect 10: contrato OpenAPI con x-ibm-configuration, Client ID y Client Secret, producto con planes y límites, y validación y publicación con el CLI apic.

Leer la guía 7 min de lectura

IntegraciónIntermedio

Comandos básicos de administración de TIBCO ActiveSpaces 5.2

Los comandos del día a día en TIBCO ActiveSpaces 5.2: servicio de realm sobre servidores FTL, tibdg, definición del grid, tablas, arranque de procesos, estado, escalado con copysets, checkpoints y logs.

Leer la guía 8 min de lectura

DevOpsBásico

Estructura básica de un CI/CD con GitHub Actions

Un pipeline completo con GitHub Actions: pruebas en cada push y pull request, imagen Docker en GitHub Container Registry y despliegue a un entorno protegido, con un workflow listo para copiar.

Leer la guía 6 min de lectura

DesarrolloBásico

Buenas prácticas de desarrollo en Java con Spring Boot

Las prácticas que más se notan en un servicio Spring Boot: estructura, inyección por constructor, DTOs, validación, errores, configuración, transacciones, logs, comentarios, pruebas y calidad automatizada.

Leer la guía 8 min de lectura

Contacto

Construye hoy tu próxima ventaja competitiva

Hablemos sobre cómo podemos ayudarte. Te respondemos con una propuesta técnica clara, sin compromiso.

Solicita información

Los campos marcados con son obligatorios.