Descope Auth API

openapi: 3.0.3
info:
  title: Descope Apps Auth API
  description: Descope API
  contact:
    name: Descope
    url: https://descope.com
    email: support@descope.com
  version: 0.0.1
servers:
- url: https://api.descope.com
  description: Descope Production
- url: '{customUrl}'
  description: Custom server URL
  variables:
    customUrl:
      default: https://api.descope.com
      description: Your Descope API base URL
security:
- Descope Project ID: []
  Descope Project ID:Refresh JWT: []
  Descope Project ID:Session JWT: []
  Descope Project ID and Management Key: []
  Descope Project ID:Access Key: []
tags:
- name: Auth
paths:
  /v1/auth/saml/idp/initiate:
    get:
      tags:
      - Auth
      summary: SAML IDP Initiate Redirect
      description: SAML IDP Initiate HTTP redirect binding login flow
      operationId: SAMLIDPInitiateHTTPRedirectBinding
      parameters:
      - name: app
        in: query
        schema:
          type: string
      - name: RelayState
        in: query
        schema:
          type: string
      - name: LoginHint
        in: query
        schema:
          type: string
      - name: tenant
        in: query
        schema:
          type: string
      - name: flow_token
        in: query
        schema:
          type: string
      - name: login_hint
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: SAML IDP Initiate Redirect | Federated Apps
        description: SAML IDP Initiate HTTP redirect binding login flow
        keywords: api, federated apps
    post:
      tags:
      - Auth
      summary: SAML IDP Initiate POST
      description: SAML IDP Initiate HTTP POST binding login flow
      operationId: SAMLIDPInitiateHTTPPostBinding
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAMLIDPInitiateRequestPOST'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: SAML IDP Initiate POST | Federated Apps
        description: SAML IDP Initiate HTTP POST binding login flow
        keywords: api, federated apps
  /v1/auth/saml/idp/sso:
    get:
      tags:
      - Auth
      summary: SAML IDP Redirect Binding
      description: SAML IDP http redirect binding login flow
      operationId: SAMLIDPHTTPRedirectBinding
      parameters:
      - name: app
        in: query
        schema:
          type: string
      - name: SAMLRequest
        in: query
        schema:
          type: string
      - name: SamlRequest
        in: query
        schema:
          type: string
      - name: RelayState
        in: query
        schema:
          type: string
      - name: LoginHint
        in: query
        schema:
          type: string
      - name: tenant
        in: query
        schema:
          type: string
      - name: flow_token
        in: query
        schema:
          type: string
      - name: login_hint
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: SAML IDP Redirect Binding | Federated Apps
        description: SAML IDP http redirect binding login flow
        keywords: api, federated apps
    post:
      tags:
      - Auth
      summary: SAML IDP POST Binding
      description: SAML IDP HTTP POST binding login flow
      operationId: SAMLIDPHTTPPostBinding
      parameters:
      - name: app
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAMLIDPSSORequestPOSTData'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: SAML IDP POST Binding | Federated Apps
        description: SAML IDP HTTP POST binding login flow
        keywords: api, federated apps
  /v1/auth/saml/idp/sso-finish:
    post:
      tags:
      - Auth
      summary: SAML IDP Finish
      description: SAML IDP finish endpoint
      operationId: SAMLIDPFinishEndpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAMLIDPFinishEndpointRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLIDPFinishEndpointResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: SAML IDP Finish | Federated Apps
        description: SAML IDP finish endpoint
        keywords: api, federated apps
  /v1/auth/wsfed/idp/initiate:
    get:
      tags:
      - Auth
      summary: WS-Fed IDP Initiate
      description: WS-Fed IDP-initiated sign-in (GET)
      operationId: WSFedIDPInitiateGet
      parameters:
      - name: app
        in: query
        schema:
          type: string
      - name: tenant
        in: query
        schema:
          type: string
      - name: login_hint
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: WS-Fed IDP Initiate | Federated Apps
        description: WS-Fed IDP-initiated sign-in (GET)
        keywords: api, federated apps
    post:
      tags:
      - Auth
      summary: WS-Fed IDP Initiate
      description: WS-Fed IDP-initiated sign-in (POST)
      operationId: WSFedIDPInitiatePost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WSFedIDPInitiateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: WS-Fed IDP Initiate | Federated Apps
        description: WS-Fed IDP-initiated sign-in (POST)
        keywords: api, federated apps
  /v1/auth/wsfed/idp/sso:
    get:
      tags:
      - Auth
      summary: WS-Fed IDP Passive
      description: WS-Fed IDP passive sign-in endpoint (GET)
      operationId: WSFedIDPPassiveGet
      parameters:
      - name: app
        in: query
        schema:
          type: string
      - name: wa
        in: query
        schema:
          type: string
      - name: wtrealm
        in: query
        schema:
          type: string
      - name: wreply
        in: query
        schema:
          type: string
      - name: wctx
        in: query
        schema:
          type: string
      - name: whr
        in: query
        schema:
          type: string
      - name: tenant
        in: query
        schema:
          type: string
      - name: login_hint
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: WS-Fed IDP Passive | Federated Apps
        description: WS-Fed IDP passive sign-in endpoint (GET)
        keywords: api, federated apps
    post:
      tags:
      - Auth
      summary: WS-Fed IDP Passive
      description: WS-Fed IDP passive sign-in endpoint (POST)
      operationId: WSFedIDPPassivePost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WSFedIDPPassiveRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: WS-Fed IDP Passive | Federated Apps
        description: WS-Fed IDP passive sign-in endpoint (POST)
        keywords: api, federated apps
  /v1/auth/wsfed/idp/sso-finish:
    post:
      tags:
      - Auth
      summary: WS-Fed IDP Finish
      description: WS-Fed IDP finish endpoint after authentication
      operationId: WSFedIDPFinishEndpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WSFedIDPFinishEndpointRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WSFedIDPFinishEndpointResponse'
      x-publishYaml: federatedApps
      security: []
      x-meta:
        title: WS-Fed IDP Finish | Federated Apps
        description: WS-Fed IDP finish endpoint after authentication
        keywords: api, federated apps
  /v1/auth/accesskey/exchange:
    post:
      tags:
      - Auth
      summary: Exchange Key
      description: '### Exchange API key for access token


        This API Endpoint will take an API key for the project and provide an access token to be used for accessing the application.

        The session token JWT token will be valid for the configured [Session Token Timeout](/project-settings#session-token-timeout), and its expiration time will be provided in the `expiration` field of the response object.'
      operationId: ExchangeAccessKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeAccessKeyRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeAccessKeyResponse'
      security:
      - Descope Project ID:Access Key: []
      x-order: 3
      x-publishYaml: AccessKeys
      x-meta:
        title: Exchange Key | Access Keys
        description: Exchange API key for access token
        keywords: api, access keys
  /v1/auth/refresh:
    post:
      tags:
      - Auth
      summary: Refresh Session
      description: '### Refresh the session token, using a valid fresh token


        This API endpoint will provide a new valid session token for an existing signed-in user, by validating the provided refresh token.

        The refresh token is provided as part of the HTTP Authorization Bearer.'
      operationId: RefreshSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshSessionRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-order: 2
      x-publishYaml: session
      x-meta:
        title: Refresh Session | Session
        description: Refresh the session token, using a valid fresh token
        keywords: api, session
  /v1/auth/try-refresh:
    post:
      tags:
      - Auth
      summary: Try Refresh Session
      description: Refresh the current session if it is valid, will not fail if the refresh token is missing or invalid
      operationId: TryRefreshSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshSessionRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionalJWTResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-order: 2
      x-publishYaml: session
      x-meta:
        title: Try Refresh Session | Session
        description: Refresh the current session if it is valid, will not fail if the refresh token is missing or invalid
        keywords: api, session
  /v1/auth/me:
    get:
      tags:
      - Auth
      summary: My Details
      description: '### Get current signed-in user details


        This API Endpoint will return the current user''s details. This endpoint requires the user to be signed in and have a valid `refreshJwt`. The `refreshJwt` is then used as part of the Authorization Bearer to perform this task.'
      operationId: Me
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseUser'
      security:
      - Descope Project ID:Refresh JWT: []
      x-order: 3
      x-publishYaml: session
      x-meta:
        title: My Details | Session
        description: Get current signed-in user details
        keywords: api, session
  /v1/auth/me/history:
    get:
      tags:
      - Auth
      summary: Get Session History
      description: '### Get user''s session history


        This API Endpoint will return the current user''s session history including geo-location and IP address. This endpoint requires the user to be signed in and have a valid `refreshJwt`. The `refreshJwt` is then used as part of the Authorization Bearer to perform this task.'
      operationId: MeAuthHistory
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeAuthHistoryResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-order: 3
      x-publishYaml: session
      x-meta:
        title: Get Session History | Session
        description: Get user's session history
        keywords: api, session
  /v1/auth/tenant/select:
    post:
      tags:
      - Auth
      summary: Select an active tenant
      description: '### Set the active tenant for the user''s current session


        This endpoint allows you to get a new session token and refresh token with the `dct` claim on the JWT which shows the active selected tenant for the user.


        See [Tenant Selection Article](/knowledgebase/descopeflows/tenantselectcomponent/) for more details of the usage.'
      operationId: SelectTenant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectTenantRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-order: 3
      x-publishYaml: session
      x-meta:
        title: Select an active tenant | Session
        description: Set the active tenant for the user's current session
        keywords: api, session
  /v1/auth/idp/sso/logout:
    get:
      tags:
      - Auth
      summary: Logout
      description: IDP SSO Logout from the session and delete the session and refresh cookies
      operationId: IDPSSOLogoutGet
      parameters:
      - name: app
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-order: 4
      x-publishYaml: session
      security: []
      x-meta:
        title: Logout | Session
        description: IDP SSO Logout from the session and delete the session and refresh cookies
        keywords: api, session
    post:
      tags:
      - Auth
      summary: Logout
      description: IDP SSO Logout from the session and delete the session and refresh cookies
      operationId: IDPSSOLogoutPost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IDPSSOLogoutRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
      x-order: 4
      x-publishYaml: session
      security: []
      x-meta:
        title: Logout | Session
        description: IDP SSO Logout from the session and delete the session and refresh cookies
        keywords: api, session
  /v1/auth/logout:
    post:
      tags:
      - Auth
      summary: Sign-Out
      description: '### Log the user out from the provided session

        This API endpoint will sign the user out of the provided session using the `refreshToken`.

        Successfully executing this endpoint will invalidate the provided refresh tokens.

        Response will also include all user tokens and fields empty, so the executing client will remove cookies as well.'
      operationId: Logout
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogoutRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-order: 4
      x-publishYaml: session
      x-meta:
        title: Sign-Out | Session
        description: Log the user out from the provided session
        keywords: api, session
  /v1/auth/logoutall:
    post:
      tags:
      - Auth
      summary: Sign-Out All Active Sessions
      description: '### Log the user out from all signed-in sessions


        This API endpoint will sign the user out of all the devices they are currently signed-in with.

        Successfully executing this endpoint will invalidate all user''s refresh tokens. Response will include all user tokens and fields empty, so client will remove cookies as well.'
      operationId: LogoutAllDevices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogoutRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-order: 4
      x-publishYaml: session
      x-meta:
        title: Sign-Out All Active Sessions | Session
        description: Log the user out from all signed-in sessions
        keywords: api, session
  /v1/auth/validate:
    post:
      tags:
      - Auth
      operationId: ValidateSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateSessionRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateSessionResponse'
      security:
      - Descope Project ID:Session JWT: []
      x-publishYaml: session
      summary: Validate Session
      description: '### Validate and parse a user''s session JWT.


        This endpoint is used to validate a users session using the Project ID and the user''s session JWT. Upon successful validate of the user, you will receive the parsed JWT.


        When posting to this endpoint from an application, you get the JWT from local or cookie storage, and prepend it with project ID and use that as the bearer.'
      x-meta:
        title: Validate Session | Session
        description: Validate and parse a user's session JWT.
        keywords: api, session
  /v1/auth/notp/{provider}/update:
    post:
      tags:
      - Auth
      summary: Update User NOTP
      description: Update user phone using NOTP
      operationId: UpdateUserNOTP
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserNOTPRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NOTPLinkResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: NOTP
      x-order: 3
      x-meta:
        title: Update User NOTP | NOTP
        description: Update user phone using NOTP
        keywords: api, notp
  /v1/auth/oauth/authorize:
    post:
      tags:
      - Auth
      summary: Sign-Up / Sign-In
      description: '### Authorize end user to sign-up or sign-in using social login credentials


        Initiate a social login (OAuth) sign-up or sign-in process for an end user. Descope will coordinate the authorization process with the OAUth provider specified in the `provider` field. Specify the URL you want to redirect the end user to after a successful sign-in in the `redirectURL` parameter.


        When the OAuth authorization completes successfully, the endpoint returns a URL `url` that has a unique code `<unique-code\>` appended as a URL parameter to the `redirectURL` you provided. For example, if `redirectURL = https://oauth.mycompany.com/shopping.htm` then `url = https://oauth.mycompany.com/shopping.htm?code=<unique-code\>`. The unique code will be exchanged for a valid user object in the next step.


        After the end user successfully authenticates with the OAuth provider the end user session is redirected to `url`.


        ### Next Steps

        Call the [Exchange Code](/api/oauth/exchange-code) endpoint from the flow that responds to the URL specified in the `redirectURL` field, to exchange the unique code for a user session object.


        ### See Also

        - See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.

        - See [User Login Options](/api/overview#user-login-options) for further details on the stepup, mfa, and customClaims parameters.'
      operationId: AuthorizeOAuth
      parameters:
      - name: provider
        in: query
        schema:
          type: string
      - name: redirectUrl
        in: query
        schema:
          type: string
      - name: prompt
        in: query
        schema:
          type: array
          items:
            type: string
      - name: test
        in: query
        schema:
          type: boolean
      - name: rawResponse
        in: query
        schema:
          type: boolean
      - name: loginHint
        in: query
        schema:
          type: string
      - name: initiatedEmail
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginOptions'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthRedirectResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OAuth
      x-order: 3
      x-meta:
        title: Sign-Up / Sign-In | OAuth
        description: Authorize end user to sign-up or sign-in using social login credentials
        keywords: api, oauth
  /v1/auth/oauth/authorize/signin:
    post:
      tags:
      - Auth
      summary: Create Redirect URI for Sign-In Request
      description: '### Create an OAuth Redirect URI for user Sign-In Request


        This endpoint allows you to create an OAuth Redirect URI for user Sign-Up Request.


        ### See Also

        - See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.'
      operationId: CreateOAuthRedirectURISignin
      parameters:
      - name: provider
        in: query
        schema:
          type: string
      - name: redirectUrl
        in: query
        schema:
          type: string
      - name: prompt
        in: query
        schema:
          type: array
          items:
            type: string
      - name: test
        in: query
        schema:
          type: boolean
      - name: rawResponse
        in: query
        schema:
          type: boolean
      - name: loginHint
        in: query
        schema:
          type: string
      - name: initiatedEmail
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginOptions'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthRedirectResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OAuth
      x-order: 4
      x-meta:
        title: Create Redirect URI for Sign-In Request | OAuth
        description: Create an OAuth Redirect URI for user Sign-In Request
        keywords: api, oauth
  /v1/auth/oauth/authorize/signup:
    post:
      tags:
      - Auth
      summary: Create Redirect URI for Sign-Up Request
      description: '### Create an OAuth Redirect URI for user Sign-In Request


        This endpoint allows you to create an OAuth Redirect URI for user Sign-In Request.


        ### See Also

        - See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.'
      operationId: CreateOAuthRedirectURISignup
      parameters:
      - name: provider
        in: query
        schema:
          type: string
      - name: redirectUrl
        in: query
        schema:
          type: string
      - name: prompt
        in: query
        schema:
          type: array
          items:
            type: string
      - name: test
        in: query
        schema:
          type: boolean
      - name: rawResponse
        in: query
        schema:
          type: boolean
      - name: loginHint
        in: query
        schema:
          type: string
      - name: initiatedEmail
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginOptions'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthRedirectResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OAuth
      x-order: 5
      x-meta:
        title: Create Redirect URI for Sign-Up Request | OAuth
        description: Create an OAuth Redirect URI for user Sign-In Request
        keywords: api, oauth
  /v1/auth/oauth/authorize/update:
    post:
      tags:
      - Auth
      summary: Creating OAuth redirect URI for update user request
      description: Creating OAuth redirect URI for update user request
      operationId: CreateOAuthRedirectURIUpdateUser
      parameters:
      - name: provider
        in: query
        schema:
          type: string
      - name: redirectUrl
        in: query
        schema:
          type: string
      - name: allowAllMerge
        in: query
        schema:
          type: boolean
      - name: prompt
        in: query
        schema:
          type: array
          items:
            type: string
      - name: loginHint
        in: query
        schema:
          type: string
      - name: initiatedEmail
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginOptions'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthRedirectResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-publishYaml: OAuth
      x-order: 6
      x-meta:
        title: Creating OAuth redirect URI for update user request | OAuth
        description: Creating OAuth redirect URI for update user request
        keywords: api, oauth
  /v1/auth/oauth/native/start:
    post:
      tags:
      - Auth
      summary: Starts a full OAuth flow using native APIs
      description: Starts a full OAuth flow using native APIs
      operationId: OAuthNativeStart
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthNativeStartRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthNativeStartResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OAuth
      x-order: 6
      x-meta:
        title: Starts a full OAuth flow using native APIs | OAuth
        description: Starts a full OAuth flow using native APIs
        keywords: api, oauth
  /v1/auth/oauth/exchange:
    post:
      tags:
      - Auth
      summary: Exchange Code
      description: '### Exchange OAuth code for Descope user session


        This endpoint will exchange the OAuth code for the Descope session information needed for managing the end user session. Call this endpoint from your code flow that responds to the `url` that was returned by the [Sign-In](/api/oauth/sign-up-sign-in) endpoint.


        The unique code `<unique-code\>` is appended as a URL parameter: `code=<unique-code\>`, for example, `url = https://oauth.mycompany.com/shopping.htm?code=<unique-code\>`.


        ### Next Steps


        1. Extract the unique code `<unique-code\>` from the URL parameter.

        2. Call this endpoint, passing the `<unique-code\>` as the request parameter


        The response object includes the session JWT (sessionJwt) and refresh JWT (refreshJwt) when this endpoint completes successfully.


        ### See Also

        - See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.'
      operationId: ExchangeCodeoauth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeTokenRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OAuth
      x-order: 7
      x-meta:
        title: Exchange Code | OAuth
        description: Exchange OAuth code for Descope user session
        keywords: api, oauth
  /v1/auth/oauth/native/finish:
    post:
      tags:
      - Auth
      summary: Finishes a full OAuth flow using native APIs
      description: Finishes a full OAuth flow using native APIs
      operationId: OAuthNativeFinish
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthNativeFinishRequest'
        required: true
      responses:
        '200':
          description: OK
          conten

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/descope/refs/heads/main/openapi/descope-auth-api-openapi.yml