{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"oauth-flows","__idx":0},"children":["OAuth Flows"]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["\nExcerpt from the OpenAPI 3.1 specification about the OAuth Flows object\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"oauth-flows-object","__idx":1},"children":["OAuth Flows Object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Allows configuration of the supported OAuth Flows."]},{"$$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":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["implicit"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#oauth-flow-object"},"children":["OAuth Flow Object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configuration for the OAuth Implicit flow"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["password"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#oauth-flow-object"},"children":["OAuth Flow Object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configuration for the OAuth Resource Owner Password flow"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["clientCredentials"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#oauth-flow-object"},"children":["OAuth Flow Object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configuration for the OAuth Client Credentials flow.  Previously called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application"]}," in OpenAPI 2.0."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["authorizationCode"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#oauth-flow-object"},"children":["OAuth Flow Object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configuration for the OAuth Authorization Code flow.  Previously called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accessCode"]}," in OpenAPI 2.0."]}]}]}]}]},{"$$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":2,"id":"oauth-flow-object","__idx":3},"children":["OAuth Flow Object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configuration details for a supported OAuth Flow"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fixed-fields-1","__idx":4},"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":["authorizationUrl"]},{"$$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":["oauth2"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"implicit\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"authorizationCode\""]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["tokenUrl"]},{"$$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":["oauth2"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"password\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"clientCredentials\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"authorizationCode\""]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},". The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["refreshUrl"]},{"$$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":["oauth2"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["scopes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Map[",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]},"]"]},{"$$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"]},". The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty."]}]}]}]}]},{"$$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":"oauth-flow-object-examples","__idx":5},"children":["OAuth Flow Object Examples"]},{"$$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    \"authorizationCode\": {\n      \"authorizationUrl\": \"https://example.com/api/oauth/dialog\",\n      \"tokenUrl\": \"https://example.com/api/oauth/token\",\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  authorizationCode:\n    authorizationUrl: https://example.com/api/oauth/dialog\n    tokenUrl: https://example.com/api/oauth/token\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":6},"children":["Visuals"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorization-code-with-pkce-visual","__idx":7},"children":["Authorization Code with PKCE visual"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following describes a security scheme using the Authorization Code flow with PKCE."," ","PKCE is supported by using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-usePkce"]}," specification extension."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n  securitySchemes:\n    GitLab_OAuth2AuthorizationCodeWithPKCE:\n      description: OAuth2 Authorization Code with PKCE description\n      type: oauth2\n      flows:\n        authorizationCode:\n          x-usePkce:\n            disableManualConfiguration: false\n            hideClientSecretInput: false\n          authorizationUrl: 'https://gitlab.com/oauth/authorize'\n          tokenUrl: 'https://gitlab.com/oauth/token'\n          scopes:\n            'api': Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry.\n            'read_user': Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The corresponding ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]}," interface displays the client ID and client secret fields."," ","It is possible to hide the client secret field with the  ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hideClientSecretInput"]}," field on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-usePkce"]}," object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-auth-code-pkce-1-5bdd36903825ea2c.png","alt":"Authorization Code with PKCE"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the manual configuration is not disabled, then a user can toggle the \"Configure PKCE manually\" to edit the code verifier and code challenge."," ","Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disableManualConfiguration"]}," on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-usePkce"]}," object to disable manual configuration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-auth-code-pkce-2-afbfb100f9af9a95.png","alt":"Authorization Code with PKCE"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"client-credentials-visual","__idx":8},"children":["Client Credentials visual"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Client credentials displays a client ID and client secret field in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]},"."," ","Once the token is received, it is stored for the duration of the session."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-client-credentials-0c25fbe23f98e87b.png","alt":"client credentials try it"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"implicit-flow-visual","__idx":9},"children":["Implicit flow visual"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The implicit flow description."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-implicit-1-8c78d1588e71ed75.png","alt":"implicit flow security"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The implicit flow displays a client ID field in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-implicit-2-fb7b477c560835ff.png","alt":"implicit flow try it"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"password-flow-visual","__idx":10},"children":["Password flow visual"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The password flow description."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-password-1-9e276f909efd6211.png","alt":"password flow security"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The password flow displays an access token type field and access token field in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]},"."," ","The access token type field is pre-filled with \"Bearer\" as the value."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/security-password-2-fc4e382c284ed5fd.png","alt":"password flow try it"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"types","__idx":11},"children":["Types"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OAuth2Flows"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AuthorizationCode"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ClientCredentials"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ImplicitFlow"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PasswordFlow"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const OAuth2Flows: NodeType = {\n  properties: {\n    implicit: 'ImplicitFlow',\n    password: 'PasswordFlow',\n    clientCredentials: 'ClientCredentials',\n    authorizationCode: 'AuthorizationCode',\n  },\n};\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorization-code-flow-type","__idx":12},"children":["Authorization code flow type"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const AuthorizationCode: NodeType = {\n  properties: {\n    refreshUrl: { type: 'string' },\n    authorizationUrl: { type: 'string' },\n    scopes: { type: 'object', additionalProperties: { type: 'string' } },\n    tokenUrl: { type: 'string' },\n  },\n  required: ['authorizationUrl', 'tokenUrl', 'scopes'],\n};\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"client-credentials-flow-type","__idx":13},"children":["Client credentials flow type"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const ClientCredentials: NodeType = {\n  properties: {\n    refreshUrl: { type: 'string' },\n    scopes: { type: 'object', additionalProperties: { type: 'string' } },\n    tokenUrl: { type: 'string' },\n  },\n  required: ['tokenUrl', 'scopes'],\n};\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"implicit-flow-type","__idx":14},"children":["Implicit flow type"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const ImplicitFlow: NodeType = {\n  properties: {\n    refreshUrl: { type: 'string' },\n    scopes: { type: 'object', additionalProperties: { type: 'string' } },\n    authorizationUrl: { type: 'string' },\n  },\n  required: ['authorizationUrl', 'scopes']\n};\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"password-flow-type","__idx":15},"children":["Password flow type"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const PasswordFlow: NodeType = {\n  properties: {\n    refreshUrl: { type: 'string' },\n    scopes: { type: 'object', additionalProperties: { type: 'string' } },\n    tokenUrl: { type: 'string' },\n  },\n  required: ['tokenUrl', 'scopes'],\n};\n","lang":"js"},"children":[]}]},"frontmatter":{},"tagList":["html"],"title":"OAuth Flows","lastModified":"2025-05-28T16:01:32.000Z"}