{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"security-schemes","__idx":0},"children":["Security schemes"]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["\nExcerpt from the OpenAPI 3.1 specification about the security scheme object\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-scheme-object","__idx":1},"children":["Security Scheme Object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Defines a security scheme that can be used by the operations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://tools.ietf.org/html/rfc6749"},"children":["RFC6749"]},", and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://tools.ietf.org/html/draft-ietf-oauth-discovery-06"},"children":["OpenID Connect Discovery"]},"."," ","Please note that as of 2020, the implicit flow is about to be deprecated by ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://tools.ietf.org/html/draft-ietf-oauth-security-topics"},"children":["OAuth 2.0 Security Best Current Practice"]},". Recommended for most use case is Authorization Code Grant flow with PKCE."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fixed-fields","__idx":2},"children":["Fixed Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field Name"},"children":["Field Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Applies To"},"children":["Applies To"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["type"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Any"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". The type of the security scheme. Valid values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"apiKey\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"http\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"mutualTLS\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"oauth2\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"openIdConnect\""]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Any"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A description for security scheme. ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.commonmark.org/"},"children":["CommonMark syntax"]}," MAY be used for rich text representation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". The name of the header, query or cookie parameter to be used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["in"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". The location of the API key. Valid values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"query\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"header\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"cookie\""]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["scheme"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". The name of the HTTP Authorization scheme to be used in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://tools.ietf.org/html/rfc7235#section-5.1"},"children":["Authorization header as defined in RFC7235"]},".  The values used SHOULD be registered in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml"},"children":["IANA Authentication Scheme registry"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["bearerFormat"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"bearer\""]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["flows"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/oauth-flows"},"children":["OAuth Flows Object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oauth2"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". An object containing configuration information for the flow types supported."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["openIdConnectUrl"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openIdConnect"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". 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."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This object MAY be extended with ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/specification-extensions"},"children":["Specification Extensions"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"security-scheme-object-example","__idx":3},"children":["Security Scheme Object Example"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"basic-authentication-sample","__idx":4},"children":["Basic Authentication Sample"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"http\",\n  \"scheme\": \"basic\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: http\nscheme: basic\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"api-key-sample","__idx":5},"children":["API Key Sample"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"apiKey\",\n  \"name\": \"api_key\",\n  \"in\": \"header\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: apiKey\nname: api_key\nin: header\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"jwt-bearer-sample","__idx":6},"children":["JWT Bearer Sample"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"http\",\n  \"scheme\": \"bearer\",\n  \"bearerFormat\": \"JWT\",\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: http\nscheme: bearer\nbearerFormat: JWT\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"implicit-oauth2-sample","__idx":7},"children":["Implicit OAuth2 Sample"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"oauth2\",\n  \"flows\": {\n    \"implicit\": {\n      \"authorizationUrl\": \"https://example.com/api/oauth/dialog\",\n      \"scopes\": {\n        \"write:pets\": \"modify pets in your account\",\n        \"read:pets\": \"read your pets\"\n      }\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: oauth2\nflows:\n  implicit:\n    authorizationUrl: https://example.com/api/oauth/dialog\n    scopes:\n      write:pets: modify pets in your account\n      read:pets: read your pets\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"visuals","__idx":8},"children":["Visuals"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The visuals are screenshots from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]}," console."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A security panel displays with each operation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-panel-1-4d54383a497d98a3.png","alt":"security panel"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select the security panel to expand the detailed security definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-panel-2-c8f77aa2973d5d16.png","alt":"security panel"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["See more"]}," link."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-panel-3-75fd6a915023ba6a.png","alt":"security panel"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"http-basic-visual","__idx":9},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http basic"]}," visual"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]}," panel shows username and password fields with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http basic"]}," security."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-basic-44f5cf0aff42c952.png","alt":"http basic try it"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"http-bearer-visual","__idx":10},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http bearer"]}," visual"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following security scheme describes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http bearer"]}," security."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n  securitySchemes:\n    JWT:\n      description: JWT bearer token description...\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The security description shows the http bearer description."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-http-bearer-1-0e072fb1abd3328f.png","alt":"http bearer security description"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]}," shows a field to enter the bearer token."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-http-bearer-2-df4b92a50d1f51a9.png","alt":"http bearer security description"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"apikey-visual","__idx":11},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiKey"]}," visual"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following security scheme describes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiKey"]}," in the header security."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n  securitySchemes:\n    GitLab_PersonalAccessToken:\n      description: GitLab Personal Access Token description\n      type: apiKey\n      name: PRIVATE-TOKEN\n      in: header\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The security description shows the header parameter name."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-apikey-1-5de0ed8ef172502f.png","alt":"apiKey security"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]}," panel shows the corresponding API key field."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-apikey-2-1744a02b89d4d0a3.png","alt":"apiKey security"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"oauth2-flows","__idx":12},"children":["OAuth2 flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/oauth-flows"},"children":["OAuth Flows object"]}," for examples."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"types","__idx":13},"children":["Types"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NamedSecuritySchemes"]}," (map of strings to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SecurityScheme"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SecurityScheme"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SecuritySchemeFlows"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"\nconst SecurityScheme: NodeType = {\n  properties: {\n    type: { enum: ['apiKey', 'http', 'oauth2', 'openIdConnect'] },\n    description: { type: 'string' },\n    name: { type: 'string' },\n    in: { type: 'string', enum: ['query', 'header', 'cookie'] },\n    scheme: { type: 'string' },\n    bearerFormat: { type: 'string' },\n    flows: 'SecuritySchemeFlows',\n    openIdConnectUrl: { type: 'string' },\n  },\n  required(value) {\n    switch (value?.type) {\n      case 'apiKey':\n        return ['type', 'name', 'in'];\n      case 'http':\n        return ['type', 'scheme'];\n      case 'oauth2':\n        return ['type', 'flows'];\n      case 'openIdConnect':\n        return ['type', 'openIdConnectUrl'];\n      default:\n        return ['type'];\n    }\n  },\n  allowed(value) {\n    switch (value?.type) {\n      case 'apiKey':\n        return ['type', 'name', 'in', 'description'];\n      case 'http':\n        return ['type', 'scheme', 'bearerFormat', 'description'];\n      case 'oauth2':\n        return ['type', 'flows', 'description'];\n      case 'openIdConnect':\n        return ['type', 'openIdConnectUrl', 'description'];\n      default:\n        return ['type', 'description'];\n    }\n  },\n  extensionsPrefix: 'x-',\n};\n","lang":"js"},"children":[]}]},"frontmatter":{},"tagList":["html"],"title":"Security schemes","lastModified":"2025-05-28T16:01:32.000Z"}