OpenAPI: OAuth2 Authorization Code Flow

Documenting OAuth2 Authorization Code Flow in OpenAPI

The authorization code flow is the recommended OAuth2 flow for server-side applications and SPAs. OpenAPI 3.0 has built-in support for documenting OAuth2 security schemes.

OAuth2 Security Scheme

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

Applying Scopes to Endpoints

paths:
  /users:
    get:
      summary: List users
      security:
        - OAuth2:
            - read:users
      responses:
        '200':
          description: User list
    post:
      summary: Create user
      security:
        - OAuth2:
            - write:users
      responses:
        '201':
          description: User created
  /admin/settings:
    get:
      security:
        - OAuth2:
            - admin

Scope Naming Conventions

Use a hierarchical naming pattern like resource:action:

• read:users - read access to user data
• write:users - create/update user data
• delete:users - delete user data
• admin - full access

Flow Comparison

Flow	Best For
Authorization Code	Server-side web apps, SPAs with backend
Client Credentials	Server-to-server (no user context)
Implicit (deprecated)	Legacy SPAs
PKCE	Mobile apps, single-page applications

Document which flow your API supports and provide setup instructions in the API description.