How does OpenAPI define OAuth 2.0 security flows?

How does OpenAPI define OAuth 2.0 security flows? #

OAuth 2.0 is the industry-standard authorization framework for REST APIs. It defines a family of grant types (also called “flows”) that describe how a client obtains an access token to call a protected API. The OpenAPI Specification provides a dedicated security scheme type — oauth2 — that describes all four OAuth 2.0 grant types with their authorization and token URLs, scopes, and application context. Properly documenting OAuth 2.0 in OpenAPI enables documentation portals to render interactive authentication UIs, code generators to produce complete client code, and governance tooling to enforce security coverage.

Declaring an OAuth 2.0 Security Scheme #

OAuth 2.0 security schemes are declared in components/securitySchemes:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          refreshUrl: https://auth.example.com/oauth/token
          scopes:
            read:users: Read user profiles
            write:users: Create and update users
            read:orders: Read order data
            write:orders: Create and manage orders

The flows object contains one or more grant type definitions. Each defined flow describes where tokens are obtained and what scopes protect which capabilities.

The Four OAuth 2.0 Flows #

1. Authorization Code (authorizationCode) #

The authorization code flow is the most secure and widely recommended grant type for applications where the client can keep a secret (server-side web apps) or for public clients using PKCE (mobile and single-page apps). It involves a redirect to an authorization server where the user authenticates and grants consent.

flows:
  authorizationCode:
    authorizationUrl: https://auth.example.com/oauth/authorize
    tokenUrl: https://auth.example.com/oauth/token
    refreshUrl: https://auth.example.com/oauth/token
    scopes:
      read:users: Read user profiles
      write:users: Create and modify users
  • authorizationUrl — the URL to redirect the user’s browser to for authentication and consent.
  • tokenUrl — the endpoint where the authorization code is exchanged for an access token.
  • refreshUrl — the endpoint for refreshing expired access tokens (optional, often the same as tokenUrl).
  • scopes — a map of scope names to human-readable descriptions.

Tools like Swagger UI use these fields to render an OAuth 2.0 login flow directly in the documentation portal, letting developers authenticate and make live API calls.

2. Client Credentials (clientCredentials) #

The client credentials flow is designed for machine-to-machine (M2M) communication where there is no human user involved. A service authenticates directly with its client ID and secret to obtain an access token.

flows:
  clientCredentials:
    tokenUrl: https://auth.example.com/oauth/token
    scopes:
      api:read: Read-only access to all resources
      api:write: Read and write access to all resources

This is the appropriate flow for:

  • Backend services calling other services
  • Scheduled jobs and batch processors
  • CI/CD pipelines calling deployment APIs

3. Implicit (implicit) #

The implicit flow was designed for browser-based single-page applications (SPAs) before PKCE existed. It returns the access token directly in the URL fragment after the authorization redirect, without an intermediate code exchange.

flows:
  implicit:
    authorizationUrl: https://auth.example.com/oauth/authorize
    scopes:
      read:profile: Read the user's profile

Note: The implicit flow is now considered deprecated and insecure by OAuth 2.0 Security Best Current Practice (BCP). New applications should use the authorization code flow with PKCE instead. Its presence in OpenAPI documentation signals a legacy API.

4. Resource Owner Password Credentials (password) #

The password flow allows clients to directly collect the user’s username and password and exchange them for a token. It is highly discouraged for most use cases as it requires the client to handle user credentials directly.

flows:
  password:
    tokenUrl: https://auth.example.com/oauth/token
    scopes:
      read:profile: Read the user's profile

Like the implicit flow, the password grant is considered a legacy pattern. It is only appropriate for highly trusted first-party clients or legacy systems that cannot be migrated to the authorization code flow.

Applying OAuth 2.0 Security to Operations #

Security schemes are applied at the document level (as a global default) or at the operation level. The security field takes an array of security requirement objects, where each object maps a scheme name to a list of required scopes.

Global Security #

security:
  - OAuth2:
      - read:users

All operations require the read:users scope unless overridden at the operation level.

Operation-Level Security #

paths:
  /users:
    get:
      summary: List users
      security:
        - OAuth2:
            - read:users
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized — missing or invalid token
        "403":
          description: Forbidden — token lacks required scope

  /users/{id}:
    put:
      summary: Update a user
      security:
        - OAuth2:
            - write:users
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
        "403":
          description: Forbidden

Each operation specifies exactly which scopes are required, giving consumers a precise understanding of the permissions needed.

Opting Out of Security #

An operation can explicitly opt out of the global security requirement with an empty array:

/health:
  get:
    summary: Health check
    security: []
    responses:
      "200":
        description: Service is healthy

Multiple Security Schemes #

OpenAPI supports multiple security schemes, allowing an API to support several authentication methods simultaneously:

security:
  - OAuth2:
      - read:users
  - ApiKey: []

When security requirements are listed as separate array items, they are treated as alternatives (OR logic) — a client may satisfy any one of them. Schemes listed within the same object are cumulative (AND logic) — all must be satisfied.

Documenting Scopes on the Info Object #

Some teams use the info.description or the security scheme’s description to explain scope semantics and the authorization flow to API consumers:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: >
        This API uses OAuth 2.0 with the Authorization Code + PKCE flow for
        user-facing clients and the Client Credentials flow for M2M access.
        Register your application at https://developer.example.com to obtain
        a client_id. See https://developer.example.com/oauth for full documentation.        
      flows:
        authorizationCode:
          ...
        clientCredentials:
          ...

Swagger UI OAuth 2.0 Integration #

Swagger UI reads the OAuth 2.0 flow definitions and renders an “Authorize” button that initiates the appropriate flow. For the authorization code flow, it opens a popup window to the authorizationUrl, handles the redirect, and stores the resulting token for use in subsequent “Try it out” requests. Configuring oauth2RedirectUrl in the Swagger UI configuration is required for this to work correctly.

Conclusion #

OpenAPI’s oauth2 security scheme type provides precise, machine-readable documentation for all four OAuth 2.0 grant types. By declaring scopes clearly, applying them accurately to operations, and documenting the authorization flow for consumers, API teams enable documentation portals to render interactive login flows, code generators to produce complete authentication logic, and governance tools to audit security coverage. For modern APIs, the authorization code flow with PKCE (for user-facing clients) and the client credentials flow (for M2M) are the recommended patterns to document and implement.

Last updated on April 30, 2026.

This website is not affiliated with the OpenAPI Initiative.