Skip to content

Commit 94f0ae3

Browse files
committed
Rewording security as per @handrews' summary
#4007 (comment)
1 parent 2c406f9 commit 94f0ae3

File tree

1 file changed

+10
-6
lines changed

1 file changed

+10
-6
lines changed

versions/3.1.1.md

+10-6
Original file line numberDiff line numberDiff line change
@@ -322,15 +322,19 @@ This object MAY be extended with [Specification Extensions](#specification-exten
322322

323323
###### The `security` Field
324324

325-
The `security` field describes how requests are authorized:
325+
The `security` field describes which authentication mechanisms may be expected to be relevant for this API. This field, however, does not _define_ how authentication / authorization works for this API. Think of it more as _setting expectations_.
326326

327-
- If omitted, then nothing can be inferred about the authorization requirements; the behaviour is implementation-defined.
328-
- If present but empty (`security: []`), then the behaviour is undefined.
329-
- Otherwise, it is an array of [Security Requirement Objects](#security-requirement-object), at least one of which needs to be satisfied for the request to be authorized.
327+
`security` may be specified at the [OpenAPI Object](#openapi-object) level, or at the [Operation Object](#operation-object) level, or neither, or both. The effective value of `security` for a given operation is given by the first available of:
330328

331-
Because the empty Security Requirement Object `{}` will always be satisfied, any `security` list that includes `{}` will allow all requests. In particular, `security: [{}]` means that no security schemes are in use (also known as "no security").
329+
1. the `security` value given at the Operation level (if specified);
330+
2. the `security` value given at the OpenAPI Object level (if specified);
331+
3. the empty array (`[]`).
332332

333-
Individual Operations can [override this field](#operation-security).
333+
If the effective value of `security` is the empty array (`[]`), then nothing should be inferred about authentication / authorization for this API. Maybe credentials are required, maybe not; we just don't know.
334+
335+
Otherwise, `security` is a non-empty array of [Security Requirement Objects](#security-requirement-object), and it should be inferred that at least one of these needs to be satisfied for the request to be accepted.
336+
337+
Because the empty Security Requirement Object `{}` will always be satisfied, any `security` list that includes the empty object (`{}`) may be inferred to allow all requests. In particular, `security: [{}]` is the RECOMMENDED way of saying "this API (or operation) does not require authentication".
334338

335339
#### Info Object
336340

0 commit comments

Comments
 (0)