openapi: 3.0.3
info:
  title: Descope Apps Voice Message (Phone) 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: Voice Message (Phone)
paths:
  /v1/auth/otp/signup/voice:
    post:
      tags:
      - Voice Message (Phone)
      summary: Sign-Up
      description: '### Sign-up new end user by sending an OTP code via Voice

        Initiate a sign-up process by sending a One-Time Password (OTP) to a new end user. Descope will generate and deliver the OTP code via Voice to the phone number specified. Sending multiple OTP codes (for example, when an end user tries to sign-up a second or third time) will invalidate any OTP code that has already been sent.


        This endpoint will return an empty response object when it completes successfully. The endpoint will return a failure code if the phone number is already registered.


        ### Next Steps

        Verify the OTP code using the [Verify OTP Code](/api/otp/phone/verify-otp) endpoint to complete the user sign-up process. After successfully verifying the OTP code the end user will be signed-in.


        ### 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 address and phone number.

        - Use the [Sign-In](/api/otp/phone/sign-in) endpoint to sign-in an existing end user.

        - Use the [Sign-In with Auto Sign-up](/api/otp/phone/sign-in-auto-sign-up) endpoint to create a single sign-up and sign-in flow, which will create a new end user if they are not already registered.'
      operationId: SignUpOtpVoice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OTPSignUpPhoneRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneOperationResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OTP
      x-order: 1
      x-meta:
        title: Sign-Up | OTP
        description: Sign-up new end user by sending an OTP code via Voice
        keywords: api, otp
  /v1/auth/otp/signin/voice:
    post:
      tags:
      - Voice Message (Phone)
      summary: Sign-In
      description: '### Sign-in existing end user by sending an OTP code via Voice

        Initiate a sign-in process by sending a One-Time Password (OTP) to an existing end user. Descope will generate and deliver the OTP code to the phone number specified. Sending multiple OTP codes (for example, when an end user tries to sign-in a second or third time) will invalidate any OTP code that has already been sent.


        This endpoint will return an empty response object when it completes successfully. The endpoint will return a failure code if the phone number is not yet registered.


        ### Next Steps

        Verify the OTP code using the [Verify OTP Code](/api/otp/phone/verify-otp) endpoint to complete the user sign-in process. After successfully verifying the code the end user will be signed-in.


        ### 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 address and phone number.

        - See [User Login Options](/api/overview#user-login-options) for further details on loginOptions.

        - Use the [Sign-Up](/api/otp/phone/sign-up) endpoint to sign-up a new end user.

        - Use the [Sign-In with Auto Sign-up](/api/otp/phone/sign-in-auto-sign-up) endpoint to create a single sign-up and sign-in flow, which will create a new end user if they are not already registered.'
      operationId: SignInOTPVoice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OTPSignInRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneOperationResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OTP
      x-order: 2
      x-meta:
        title: Sign-In | OTP
        description: Sign-in existing end user by sending an OTP code via Voice
        keywords: api, otp
  /v1/auth/otp/signup-in/voice:
    post:
      tags:
      - Voice Message (Phone)
      summary: Sign-In with Auto Sign-up
      description: '### Sign-in end user (with automatic sign-up) by sending an OTP code via Voice

        Initiate a process that implements both sign-in and sign-up using a single endpoint. Descope will generate and deliver the One-Time Password (OTP) to the end user via Voice. If the phone number is already registered (the end user exists) the user will be signed in. If the phone number is not registered (the end user is not yet registered) the user will be signed up. Sending multiple OTP codes (for example, when an end user tries to sign-up/sign-in a second or third time) will invalidate any OTP code that has already been sent.


        This endpoint will return an empty response object when it completes successfully.


        ### Next Steps

        Verify the OTP code using the [Verify OTP Code](/api/otp/phone/verify-otp) endpoint to complete the user sign-in process.

        After successfully verifying the code the end user will be signed-in.


        ### 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 address and phone number.

        - See [User Login Options](/api/overview#user-login-options) for further details on loginOptions.

        - Use the [Sign-Up](/api/otp/phone/sign-up) endpoint if you want a sign-up flow that will fail if the end user is already registered.

        - Use the [Sign-In](/api/otp/phone/sign-in-auto-sign-up) endpoint if you want a sign-in flow that will fail if the end user isn''t yet registered.'
      operationId: SignUpOrInOTPVoice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OTPSignInRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneOperationResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OTP
      x-order: 3
      x-meta:
        title: Sign-In with Auto Sign-up | OTP
        description: Sign-in end user (with automatic sign-up) by sending an OTP code via Voice
        keywords: api, otp
  /v1/auth/otp/verify/voice:
    post:
      tags:
      - Voice Message (Phone)
      summary: Verify OTP Code
      description: '### Verify the validity of an OTP code via Voice


        Verify that the OTP code entered by the end user matches the OTP code that was sent. The Verify OTP code endpoint completes the OTP via Voice flow for:

        - [Sign-Up](/api/otp/phone/sign-up)

        - [Sign-In](/api/otp/phone/sign-in)

        - [Sign-In with Auto Sign-up](/api/otp/phone/sign-in-auto-sign-up)

        - [Update Phone](/api/otp/phone/update-phone)


        The response object includes the session JWT `sessionJwt` and refresh JWT `refreshJwt` when it completes successfully, and the end user will be signed in. For an update phone number flow, the new phone number will replace the original phone number.


        ### 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 address and phone number.'
      operationId: VerifyCodeVoice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OTPVerifyCodeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: OTP
      x-order: 4
      x-meta:
        title: Verify OTP Code | OTP
        description: Verify the validity of an OTP code via Voice
        keywords: api, otp
  /v1/auth/otp/update/phone/voice:
    post:
      tags:
      - Voice Message (Phone)
      summary: Update Phone
      description: '### Update phone number of Existing User

        Update the phone number of an existing end user by sending an OTP code to the new phone number. After successfully verifying the code the new phone number will be used to deliver new OTP messages via Voice. The bearer token requires both the ProjectId and refresh JWT in the format `<Project ID>:<JWT>`, and can therefore only be run for end users who are currently signed-in.


        This endpoint will return an empty response object when it completes successfully.


        Descope allows you to associating multiple login IDs for a user during API update calls. For details on how this feature works, please review the details [here](/manage/users#associating-multiple-login-ids-for-a-user).


        ### Next Steps

        Verify the OTP code using the [Verify OTP Code](/api/otp/phone/verify-otp) endpoint to complete the update process.

        After successfully verifying the code the newphone number will replace the original phone number.


        ### 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 address and phone number.

        - Successful execution will return an empty body

        - To try this endpoint - need to provide `Project ID:Refresh JWT` as bearer. You can acquire the Session JWT by signing in the user and collecting it from the response.'
      operationId: UpdateUserPhoneOTPVoice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserPhoneOTPRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneOperationResponse'
      security:
      - Descope Project ID:Refresh JWT: []
      x-publishYaml: OTP
      x-order: 5
      x-meta:
        title: Update Phone | OTP
        description: Update phone number of Existing User
        keywords: api, otp
components:
  schemas:
    PhoneSignUpUserObject:
      type: object
      properties:
        username:
          type: string
          description: Username Username
        name:
          type: string
          description: Name Name
        email:
          type: string
          description: Email Email
        icon:
          type: string
    ResponseUser:
      type: object
      properties:
        loginIds:
          type: array
          items:
            type: string
        userId:
          type: string
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        verifiedEmail:
          type: boolean
        verifiedPhone:
          type: boolean
        roleNames:
          type: array
          items:
            type: string
        userTenants:
          type: array
          items:
            $ref: '#/components/schemas/UserTenants'
        status:
          type: string
        externalIds:
          type: array
          items:
            type: string
        picture:
          type: string
        test:
          type: boolean
          default: false
        customAttributes:
          type: object
          description: Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays.
          additionalProperties:
            type: string
          example:
            attribute-key: attribute-value
        createdTime:
          type: integer
          format: int32
        TOTP:
          type: boolean
          default: false
        SAML:
          type: boolean
          default: false
        OAuth:
          type: object
          additionalProperties:
            type: boolean
            default: false
        webauthn:
          type: boolean
        password:
          type: boolean
        ssoAppIds:
          type: array
          items:
            type: string
        givenName:
          type: string
        middleName:
          type: string
        familyName:
          type: string
        editable:
          type: boolean
        SCIM:
          type: boolean
        push:
          type: boolean
        permissions:
          type: array
          items:
            type: string
        OIDC:
          type: boolean
        consentExpiration:
          type: integer
          format: int32
        recoveryEmail:
          type: string
        verifiedRecoveryEmail:
          type: boolean
        recoveryPhone:
          type: string
        verifiedRecoveryPhone:
          type: boolean
    LoginOptions:
      type: object
      properties:
        stepup:
          type: boolean
          default: false
        customClaims:
          type: object
          description: Custom claims to include in the JWT as key-value pairs. Keys must be strings; values can be strings, numbers, or booleans.
          additionalProperties:
            type: string
          example:
            claim-name: claim-value
        mfa:
          type: boolean
          default: false
        ssoAppId:
          type: string
        templateOptions:
          type: object
          additionalProperties:
            type: string
        locale:
          type: string
        pkceChallenge:
          type: string
          description: relevant only for enchanted links in the point in time - other methods will ignore this field
          format: bytes
        revokeOtherSessions:
          type: boolean
        revokeOtherSessionsTypes:
          type: array
          items:
            type: string
        tenantId:
          type: string
    UserTenants:
      type: object
      properties:
        tenantId:
          type: string
        roleNames:
          type: array
          items:
            type: string
        tenantName:
          type: string
        permissions:
          type: array
          items:
            type: string
    OTPSignInRequest:
      type: object
      properties:
        loginId:
          type: string
        loginOptions:
          $ref: '#/components/schemas/LoginOptions'
        providerId:
          type: string
        ssoAppId:
          type: string
        useRecovery:
          type: boolean
    JWTResponse:
      type: object
      properties:
        sessionJwt:
          type: string
        refreshJwt:
          type: string
        cookieDomain:
          type: string
        cookiePath:
          type: string
        cookieMaxAge:
          type: integer
          format: int32
        cookieExpiration:
          type: integer
          format: int32
        user:
          $ref: '#/components/schemas/ResponseUser'
        firstSeen:
          type: boolean
        idpResponse:
          $ref: '#/components/schemas/IDPResponse'
        sessionExpiration:
          type: integer
          format: int32
        externalToken:
          type: string
        claims:
          type: object
        tenantSSOID:
          type: string
        trustedDeviceJwt:
          type: string
        nextRefreshSeconds:
          type: integer
          format: int32
        cookieName:
          type: string
        sessionCookieName:
          type: string
        sessionCookieDomain:
          type: string
        unsavedSSO:
          type: boolean
      description: 'NOTE: if you add a new field to this message, also add it to the OptionalJWTResponse message'
    PhoneOperationResponse:
      type: object
      properties:
        maskedPhone:
          type: string
        verificationAttempts:
          type: integer
          format: int32
    SignupLoginOptions:
      type: object
      properties:
        customClaims:
          type: object
          description: Custom claims to include in the JWT as key-value pairs. Keys must be strings; values can be strings, numbers, or booleans.
          additionalProperties:
            type: string
          example:
            claim-name: claim-value
        templateOptions:
          type: object
          additionalProperties:
            type: string
        locale:
          type: string
        pkceChallenge:
          type: string
          description: relevant only for enchanted links in the point in time - other methods will ignore this field
          format: bytes
        tenantId:
          type: string
    OTPSignUpPhoneRequest:
      type: object
      properties:
        phone:
          type: string
        loginId:
          type: string
        user:
          $ref: '#/components/schemas/PhoneSignUpUserObject'
        providerId:
          type: string
        loginOptions:
          $ref: '#/components/schemas/SignupLoginOptions'
    OTPVerifyCodeRequest:
      type: object
      properties:
        loginId:
          type: string
        code:
          type: string
    UpdateUserPhoneOTPRequest:
      type: object
      properties:
        loginId:
          type: string
        phone:
          type: string
        addToLoginIDs:
          type: boolean
          default: false
        onMergeUseExisting:
          type: boolean
          default: false
        providerId:
          type: string
        templateOptions:
          type: object
          additionalProperties:
            type: string
        locale:
          type: string
        failOnConflict:
          type: boolean
    IDPResponse:
      type: object
      properties:
        samlResponse:
          type: string
        samlGeneratedUser:
          type: string
        samlGeneratedRoles:
          type: string
        oidcResponse:
          type: string
        oidcGeneratedUser:
          type: string
        oidcGeneratedRoles:
          type: string
        idpGroups:
          type: array
          items:
            type: string
        idpSAMLAttributes:
          type: object
          default: false
        idpOIDCClaims:
          type: object
  securitySchemes:
    Descope Project ID:
      type: http
      scheme: bearer
      bearerFormat: Project ID
      description: Project ID as bearer token.
    Descope Project ID:Refresh JWT:
      type: http
      scheme: bearer
      bearerFormat: Project ID:Refresh JWT
      description: Project ID:Refresh JWT as bearer token.
    Descope Project ID:Access Key:
      type: http
      scheme: bearer
      bearerFormat: ProjectId:AccessKey
      description: Project ID:Access Key as bearer token.
    Descope Project ID:Session JWT:
      type: http
      scheme: bearer
      bearerFormat: Project ID:Session JWT
      description: Project ID:Session JWT as bearer token.
    Descope Project ID and Management Key:
      type: http
      description: Project ID:Management Key as bearer token.
      scheme: bearer
      bearerFormat: ProjectId:ManagementKey
externalDocs:
  description: Descope Server
  url: https://docs.descope.com