Last updated

Security schemes

Excerpt from the OpenAPI 3.1 specification about the security scheme object

Security Scheme Object

Defines a security scheme that can be used by the operations.

Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in RFC6749, and OpenID Connect Discovery. Please note that as of 2020, the implicit flow is about to be deprecated by OAuth 2.0 Security Best Current Practice. Recommended for most use case is Authorization Code Grant flow with PKCE.

Fixed Fields
Field NameTypeApplies ToDescription
typestringAnyREQUIRED. The type of the security scheme. Valid values are "apiKey", "http", "mutualTLS", "oauth2", "openIdConnect".
descriptionstringAnyA description for security scheme. CommonMark syntax MAY be used for rich text representation.
namestringapiKeyREQUIRED. The name of the header, query or cookie parameter to be used.
instringapiKeyREQUIRED. The location of the API key. Valid values are "query", "header" or "cookie".
schemestringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormatstringhttp ("bearer")A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
flowsOAuth Flows Objectoauth2REQUIRED. An object containing configuration information for the flow types supported.
openIdConnectUrlstringopenIdConnectREQUIRED. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. The OpenID Connect standard requires the use of TLS.

This object MAY be extended with Specification Extensions.

Security Scheme Object Example
Basic Authentication Sample
{
  "type": "http",
  "scheme": "basic"
}

type: http
scheme: basic
API Key Sample
{
  "type": "apiKey",
  "name": "api_key",
  "in": "header"
}

type: apiKey
name: api_key
in: header
JWT Bearer Sample
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
}

type: http
scheme: bearer
bearerFormat: JWT
Implicit OAuth2 Sample
{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

Visuals

The visuals are screenshots from the Try it console.

A security panel displays with each operation.

security panel

Select the security panel to expand the detailed security definition.

security panel

For operations that use multiple security schemes, Redocly displays a summary followed by the description of each security definition. If the description is too long, Redocly displays a truncated description with a See more link.

security panel

http basic visual

The Try it panel shows username and password fields with http basic security.

http basic try it

http bearer visual

The following security scheme describes http bearer security.

components:
  securitySchemes:
    JWT:
      description: JWT bearer token description...
      type: http
      scheme: bearer
      bearerFormat: JWT

The security description shows the http bearer description.

http bearer security description

The Try it shows a field to enter the bearer token.

http bearer security description

apiKey visual

The following security scheme describes an apiKey in the header security.

components:
  securitySchemes:
    GitLab_PersonalAccessToken:
      description: GitLab Personal Access Token description
      type: apiKey
      name: PRIVATE-TOKEN
      in: header

The security description shows the header parameter name. apiKey security

The Try it panel shows the corresponding API key field. apiKey security

OAuth2 flows

See the OAuth Flows object for examples.

Types

  • NamedSecuritySchemes (map of strings to SecurityScheme)
  • SecurityScheme
  • SecuritySchemeFlows

const SecurityScheme: NodeType = {
  properties: {
    type: { enum: ['apiKey', 'http', 'oauth2', 'openIdConnect'] },
    description: { type: 'string' },
    name: { type: 'string' },
    in: { type: 'string', enum: ['query', 'header', 'cookie'] },
    scheme: { type: 'string' },
    bearerFormat: { type: 'string' },
    flows: 'SecuritySchemeFlows',
    openIdConnectUrl: { type: 'string' },
  },
  required(value) {
    switch (value?.type) {
      case 'apiKey':
        return ['type', 'name', 'in'];
      case 'http':
        return ['type', 'scheme'];
      case 'oauth2':
        return ['type', 'flows'];
      case 'openIdConnect':
        return ['type', 'openIdConnectUrl'];
      default:
        return ['type'];
    }
  },
  allowed(value) {
    switch (value?.type) {
      case 'apiKey':
        return ['type', 'name', 'in', 'description'];
      case 'http':
        return ['type', 'scheme', 'bearerFormat', 'description'];
      case 'oauth2':
        return ['type', 'flows', 'description'];
      case 'openIdConnect':
        return ['type', 'openIdConnectUrl', 'description'];
      default:
        return ['type', 'description'];
    }
  },
  extensionsPrefix: 'x-',
};