API · Developer Guide

OpenAPI Security Best Practices: Declarations and Runtime Checks

A declared security requirement documents the contract; it does not enforce access. Use this workflow to review a specification change and identify the runtime evidence still needed before release.

Define a mechanism, then require it

components.securitySchemes names the mechanisms. The security field applies requirements globally or per operation. Merely defining a bearer scheme does not require a token.

An operation-level security array replaces the global array. security: [] removes inherited requirements; security: [{}] declares anonymous access. Separate objects in the array are alternatives (OR); names in one object must all be satisfied (AND). A named bearer requirement with an empty scope array is not an anonymous alternative.

Example: review public and protected operations

Paste the entire document into OpenAPI Security Checker and select Check Security. /account inherits bearerAuth. /public-info clears it. /optional-login permits anonymous access. /partner requires both named mechanisms. The HTTPS server is illustrative; the checker never contacts it.

Complete OpenAPI document for Security Checker

openapi: 3.1.0
info: {title: Security Review API, version: "1.0.0"}
servers:
  - url: https://api.example.com
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer}
    clientKey: {type: apiKey, in: header, name: X-Client-Key}
security:
  - bearerAuth: []
paths:
  /account:
    get:
      responses:
        "200": {description: Account returned}
  /public-info:
    get:
      security: []
      responses:
        "200": {description: Public information}
  /optional-login:
    get:
      security:
        - bearerAuth: []
        - {}
      responses:
        "200": {description: Public or personalized information}
  /partner:
    get:
      security:
        - bearerAuth: []
          clientKey: []
      responses:
        "200": {description: Partner information}

Interpret the report before changing the contract

Neither line proves a vulnerability. Confirm whether those operations are intentionally public, what data they return, and whether the deployed service follows that policy. Do not remove public access just to make a report quiet.

The sample uses clientKey on /partner, so it is not reported unused. If clientKey is removed from the /partner requirement, review the unused scheme warning before deleting a definition shared with another contract. The checker counts use only in the inline operations it inspects.

Expected checker output

GET /public-info has no declared security requirement.
Review: GET /optional-login declares an anonymous access alternative (security includes {}). Public access may be intentional.

What the local checker actually inspects

It does not fully resolve $ref, validate scheme definitions or OAuth scope semantics, or inspect every OpenAPI location. A malformed security object may escape these selected checks. Use a version-aware specification validator and inspect referenced definitions separately; Small Tools OpenAPI Validator also performs selected structural checks, not full compliance validation.

Missing or empty effective security arrays on inspected inline operations, including operation overrides of global security.
Empty requirement objects that allow anonymous access, scheme names absent from components.securitySchemes, and definitions unused by inspected operations.
Document-level servers whose URL starts with http://. It does not check path/operation server overrides, deployed HTTPS redirects, certificates, or negotiated TLS.

Check enforcement in an environment you control

OWASP identifies missing object-level authorization as a separate API risk. Successfully authenticating a caller does not establish permission to read another caller’s records. Plan authorization tests alongside contract review.

In your own test environment, create synthetic users A and B and separate test records. Record which roles may read or change each record.
Test the allowed owner/role path and the disallowed cross-user path. Verify both response data and side effects; a status code alone is insufficient evidence.
Test missing, invalid, expired, and insufficient-permission credentials against the intended policy. Keep fixtures and credentials out of public reports.
Confirm HTTPS behavior at the deployed entry point separately. Save test results and the contract revision in the release review. Small Tools does not run these tests.

Common review mistakes

Adding a scheme definition without applying a requirement to the intended operations.
Putting two schemes in different array entries when both are required, or accidentally overriding a global requirement on one operation.
Treating a public endpoint warning as an automatic defect instead of reviewing its intended audience and response fields.
Treating a clean declaration report as evidence of token verification, resource ownership enforcement, rate limiting, or a complete security audit.

Frequently asked questions

Does Security Checker verify bearer tokens? No. It reads the specification and does not validate signatures, issuer, audience, expiry, or actual access decisions.

Why is a declared scheme reported undefined? The effective requirement uses a name absent from components.securitySchemes. Check spelling and the document you supplied; resolving referenced scheme definitions still needs separate review.

Can I switch from AND to OR without breaking anything? That changes the declared access policy. Review both server enforcement and client expectations with the API owner; the checker does not classify that policy change.

Does a clean result mean the API is secure? No. It means these selected configuration checks found no issues in the supplied document. Runtime controls and unsupported specification rules still require evidence.

Privacy when reviewing an API contract

These linked transformations process input locally in the browser without uploading it to Small Tools servers. They do not fetch referenced documents or call the described API. Redact embedded credentials, private hostnames, and identifying examples before sharing a contract, screenshot, or copied report. The report is not a redaction tool.

Related tools

OpenAPI Security Checker — Review declared security, anonymous access alternatives, unused schemes, and HTTP server URLs.
OpenAPI Validator — Check OpenAPI documents for valid YAML or JSON and essential structure.
OpenAPI Schema Viewer — Inspect component schemas, fields, required values, and references.
HTTP Header Builder — Validate and normalize an HTTP header block for a request.

Browse OpenAPI & API tools →

References

Browse all developer guides →