An OpenAPI document can describe that an operation uses a bearer token, an OAuth scope, an API key, or no credentials at all. That description is useful for clients, documentation, and test generation. It is not an enforcement point. A server that publishes a security requirement has not necessarily implemented the object-level authorization that the endpoint needs.

The OpenAPI Specification separates securitySchemes from security requirements. A security scheme defines the reusable mechanism. A security requirement names one or more schemes and, for OAuth or OpenID Connect, the scopes needed for the operation. A list of requirement objects describes alternatives: only one requirement object needs to be satisfied unless the document defines a more complex combination.

Read the effective requirement

An operation-level security declaration replaces the root-level declaration for that operation. The OWASP REST assessment guidance calls for a per-operation test matrix built from the effective requirement. Test each operation with no credentials, a valid token, and a token that lacks the declared requirement. A root-level scheme does not prove that a sensitive endpoint has the same policy.

The scheme type also matters. HTTP basic authentication, API keys, bearer tokens, and OAuth 2.0 are different credential formats with different lifecycle and revocation properties. An OAuth scope can limit which operations a token may call, but it does not tell the server which database row the user may read. That decision belongs in application authorization code.

Do not infer authorization from a route name or an HTTP method. GET /orders/{id} needs a decision for the specific order. POST /orders/{id}/cancel needs a decision that includes the current state of the order, the caller's role, and the policy for cancellation. The OpenAPI operation can document the expected credential and response, but the server must enforce the rule.

Separate authentication from object access

Authentication establishes a subject. Object-level authorization asks whether that subject may act on this object. The OWASP API Security Top 10 lists Broken Object Level Authorization as a leading risk because APIs expose identifiers that clients can change. Comparing the caller's user ID with a parameter is not sufficient when roles, sharing rules, tenant ownership, or delegated access also apply.

Build a policy function per resource type. Load the object's ownership and tenant fields before applying the decision. Use a deny-by-default path for unknown actions and unexpected roles. Return the same kind of error for an object that does not exist and an object the user may not see when the distinction would leak information.

Test both horizontal and vertical movement. A low-privilege user should not become another tenant's user by changing an identifier. A user with a normal role should not gain an administrative operation by calling a route the UI does not show. These are different tests from credential validation.

Generate tests from the contract

Use the OpenAPI document to enumerate operations and their effective security requirements. Attach test identities to each requirement and compare the actual response with the intended authorization policy. Include an empty token, an expired token, a valid token with a removed scope, and a token from another tenant.

If the API supports API keys, decide whether the key represents a user, a service, or an application. Record the owner and permissions. Rotate keys and revoke them through the same lifecycle as other credentials. A key in a query string may appear in proxy logs and browser history, so choose its location deliberately.

Keep the API specification and the implementation tests in version control. A specification change that adds a new operation should fail the test suite until the operation has an authorization decision. A gateway policy can add a useful layer, but it should not be the only place where object ownership is checked.

Review the evidence after an incident

Log the authenticated subject, tenant, operation, target object, policy decision, and request identifier. Do not log the credential. A denied request should show which policy branch rejected it. An allowed request should be attributable to the identity that made it.

OpenAPI is a strong way to describe an interface. It is not a security model for the data behind the interface. The working combination is a clear credential contract, generated negative tests, server-side authorization for every object, and logs that show the decision. Without those pieces, a polished security scheme can describe access that the application never actually enforces.

References