Skip to main content

🔐 Authentication and Authorization

After covering Status Codes

in the last section, we shift focus to one of the most foundational aspects of secure API design: authentication and authorization.

Before any response can be returned, whether a success or a failure, your API must first determine if the user making the request is allowed to do so. This is where Authentication

and Authorization come into play.

Authentication answers the question, Who are you?
Authorization answers, What are you allowed to do?

This dual mechanism ensures your endpoints are protected from unauthorized access, misuse, and accidental data exposure. Without proper enforcement, a client application could trigger sensitive operations or overwhelm internal systems.

Understanding how these mechanisms work, and how to properly represent them in your OpenAPI spec

, is critical for any developer, architect, or technical writer working with APIs.

🔑 Common Authentication Types​

🔓
None
Open Access
🪪
Basic
Username/Password
🛡️
Bearer
Token Header
🔁
OAuth2
Third-Party Consent
🔐
API Key
Query or Header

Figure 1. Timeline showing common authentication types, ordered by simplicity and modernity.

Open APIs may begin with no authentication, but this is rare and typically unsafe for production. Basic authentication uses a base64-encoded

username and password combination; it is mostly used for internal tools and rarely recommended publicly.

Bearer token authentication is the current industry standard. It requires clients to send a token, usually a JWT

, in the request header. OAuth2 builds on this concept, supporting delegated permissions from trusted identity providers such as Google, GitHub, or Okta.

Each method involves trade-offs in simplicity, security, and scalability. Your API’s audience, data sensitivity, and infrastructure will determine the best fit for your needs.

🧪 Securing Your OpenAPI Spec​

Bearer Token Configuration in OpenAPI
1components:
2securitySchemes:
3  bearerAuth:
4    type: http
5    scheme: bearer
6    bearerFormat: JWT
7security:
8- bearerAuth: []

Figure 2. Configuring global bearer token support in your OpenAPI 3.0 spec.

This OpenAPI snippet defines a global security scheme using JWT bearer tokens. Once declared under components.securitySchemes, the token can be applied globally or selectively through the security object for individual endpoints.

In Swagger UI

, this configuration displays a lock icon and enables the “Authorize” button, allowing users to paste in a token. From that point on, the token is automatically attached to all test calls in the interface.

This pattern is essential when you're building interactive developer portals or generating secure client SDKs using OpenAPI tooling. It also works across tools like Redoc, and must be manually configured in Postman unless scripted.

🚨 What Happens When Auth Fails?​

🔒
401
Unauthorized — Invalid or Missing Token
⛔
403
Forbidden — Valid Token, Wrong Scope

Figures 3 and 4: A 401 error appears when the Authorization header is missing or the token is malformed. A 403 error indicates the user is authenticated but lacks permission for the requested action.

It is common for newer developers to confuse 401 and 403. A 401 status means the system could not verify the user's identity, usually because the token is missing, expired, or invalid. A 403 indicates that the token is present and valid, but the user does not have permission to access the requested resource.

Ensure your API responses clearly reflect this distinction. Messages should avoid exposing sensitive detail and instead guide users toward corrective action. During testing in Swagger or Postman, these codes will appear frequently, making proper feedback and logging essential for a great developer experience.

🧭 Understanding Token Scopes​

JWT with Scoped Access
1{
2"sub": "user_abc",
3"scope": "read:users write:billing",
4"iat": 1718393011,
5"exp": 1718493011
6}

Figure 5. A JWT payload containing scoped permissions that limit user access by category.

In token-based systems, scopes are used to narrow a user’s access. The example above includes both read and write scopes, meaning the token holder can view user data and update billing records.

Scopes should be validated during each request using middleware

or policy layers. If a user lacks the necessary scope, your API should return a 403 response and, when appropriate, include a WWW-Authenticate header to inform the client of missing privileges.

Remember, scopes are part of your API's permission model. Failing to check them is one of the most common security missteps, especially in internal or private APIs. Clarify whether your scopes follow OAuth2 conventions or are custom JWT claims, and document accordingly.

    ✅ Summary and What’s Next​

    Now that you've explored the core principles of authentication and authorization, you're equipped to secure your endpoints, define OpenAPI schemes, and guide consumers through a safe onboarding process.

    We covered:

    • Common authentication types (Bearer, OAuth2, API Keys)
    • Security definitions inside OpenAPI specs
    • JWT structure, payloads, and scopes
    • Key error codes (401 and 403) tied to auth failures

    These concepts form the backbone of secure API design. By implementing them properly, you help ensure that your platform is trustworthy, consistent, and resilient.

    In the next section, we’ll explore how endpoints are defined, grouped, and tested in live environments using tools like Swagger UI and Postman. You'll learn how to validate tokens in practice and structure your resources around secure, repeatable patterns.