On this page
At a glance#
A specification answers one question for every operation: who may call it. The answer is a security requirement, on the operation or once for the whole document. An operation that anyone may call says so explicitly.
| Rule | Meaning |
|---|---|
| A requirement on every operation | security on the operation, or at the top level of the document |
| Public on purpose | security: [] together with x-api360-public: true |
| Credentials in headers | An API key travels in a header, a bearer token in the Authorization header |
| Nothing secret in the URL | No API key, token, secret or password in a query parameter |
Credentials in a provider's specification#
A call to a product sends the app's key in the api360key header, or HTTP Basic for an app set to it. Declare it as a header scheme:
security:
- api_key: []
components:
securitySchemes:
api_key:
type: apiKey
in: header
name: api360keyThe platform's own domain APIs use a bearer token, declared as an http scheme with scheme: bearer.
Public operations#
A health probe or a file download that anyone may call states it:
/health:
get:
operationId: health
security: []
x-api360-public: trueWithout the marker, an empty security list looks like an omission and is reported.
Keep secrets out of URLs#
A URL is written to access logs, browser history and Referer headers. A query parameter named api_key, access_token, token, secret, password or similar is reported, and so is a security scheme of type apiKey located in the query. Parameter names are compared without case or separators, so Access-Token and accessToken are caught as well.
Checked by#
| Rule | Severity | Checks |
|---|---|---|
api360-operation-security | error | Every operation has an effective security requirement; security: [] needs x-api360-public: true |
api360-no-apikey-in-query | error | No apiKey scheme in the query and no credential-named query parameter |
See also#
- Authentication: what a consumer sends to a product.
- Linting a specification: run the rules on your file.