Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Security Schemes

OpenAPI API Key, Basic and Bearer (JWT) Authentication

Describe API key, HTTP Basic and Bearer token (JWT) authentication in OpenAPI: apiKey in header, query or cookie, http schemes, bearerFormat, and what each looks like on the wire.

The three simplest authentication styles are API keys, HTTP Basic and Bearer tokens. They cover a large share of real APIs, and each takes only a few lines of OpenAPI. In this lesson you define each one, apply it, and see exactly what the resulting request header looks like.

API keys (type: apiKey)

An API key is a secret string the client sends with every request. OpenAPI needs to know where (in) and under which name:

YAML
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
    ApiKeyCookie:
      type: apiKey
      in: cookie
      name: SESSION
in Request looks like
header X-API-Key: 7f3c...
query GET /pets?api_key=7f3c...
cookie Cookie: SESSION=7f3c...

Prefer the header. Query strings end up in server logs, browser history and referrer headers, which leaks the key. A key identifies the application, not a user, so do not rely on it alone for sensitive user data.

HTTP Basic (type: http, scheme: basic)

Basic authentication sends username:password encoded in Base64 in the Authorization header. Base64 is not encryption, so use it only over HTTPS.

YAML
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

Request: Authorization: Basic YW5hOnMzY3JldA== (the Base64 of ana:s3cret).

Bearer tokens (type: http, scheme: bearer)

A bearer token is any string issued earlier by a login or token endpoint. Whoever bears the token can use the API, which is why it must always travel over HTTPS.

YAML
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT       # only a hint for readers and tools

Request: Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

bearerFormat is documentation: JWT tells readers the token is a JSON Web Token (three Base64URL parts: header, payload, signature). It is not validation; OpenAPI does not verify tokens.

Other HTTP schemes (digest, negotiate, hoba...) come from the IANA authentication scheme registry. Write the registered name in scheme.

Apply them together

YAML
security:
  - BearerAuth: []              # users with a token
  - ApiKeyHeader: []            # or machine clients with a key

paths:
  /admin/stats:
    get:
      security:
        - BearerAuth: []
          ApiKeyHeader: []      # both required
      responses:
        "200": { description: OK }

(Remember the AND/OR rules from security schemes overview.)

See what goes on the wire

This stand-in turns scheme definitions and credentials into the exact request pieces a generated client would add, and decodes a JWT's payload so you can see why bearerFormat: JWT is just a hint.

Python Stand-in: build authentication headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last two lines are a warning: Base64 is an encoding, not protection. Anyone who sees a Basic header or a JWT can read what is inside. Only HTTPS keeps them private.

Choosing between them

Choosing a simple scheme

API key Identify an app or partner
Basic Quick internal tools over HTTPS
Bearer Short-lived tokens for users
1 / 2

Documenting errors and examples

  • Add a 401 response with a WWW-Authenticate header when credentials are missing.
  • Use 403 for authenticated callers who lack permission.
  • Never publish a working key or token as an example; use obviously fake values such as YOUR_API_KEY.
  • In the scheme's description (Markdown is allowed) explain where a developer gets a key or token. That one sentence saves many support emails.
YAML
ApiKeyHeader:
  type: apiKey
  in: header
  name: X-API-Key
  description: |
    Create a key in the developer dashboard under **Settings > API keys**.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which property is required for type: apiKey?

    An apiKey scheme must say where the key is sent (in) and its parameter name (name).
  2. 2. Which is the correct definition of a bearer token scheme?

    Bearer is an HTTP authentication scheme.
  3. 3. What does bearerFormat: JWT do?

    It is informational; OpenAPI does not validate tokens.
  4. 4. Why is putting an API key in the query string discouraged?

    Headers are safer because URLs leak into logs, history and referrers.
  5. 5. Is Base64 in Basic authentication encrypted?

    Base64 is trivially reversible.

Summary

  • apiKey needs in (header, query or cookie) and name; prefer headers.
  • http + scheme: basic sends Base64-encoded user:password; scheme: bearer sends a token.
  • bearerFormat is only a hint, such as JWT.
  • Always use HTTPS, document how to obtain credentials, and use fake values in examples.

Next: OAuth 2.0 and OpenID Connect