You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: versions/3.1.1.md
+10-6
Original file line number
Diff line number
Diff line change
@@ -322,15 +322,19 @@ This object MAY be extended with [Specification Extensions](#specification-exten
322
322
323
323
###### The `security` Field
324
324
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_.
326
326
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:
330
328
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 (`[]`).
332
332
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".
0 commit comments