openapi: 3.0.3
info:
  title: Descope Apps Instant Message (IM) 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: Instant Message (IM)
paths:
  /v1/auth/otp/signup/im:
    post:
      tags:
      - Instant Message (IM)
      summary: User Sign-Up (IM)
      description: Create a new user using an instant message
      operationId: SignUpOTPInstantMessage
      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: User Sign-Up (IM) | OTP
        description: Create a new user using an instant message
        keywords: api, otp
  /v1/auth/otp/signin/im:
    post:
      tags:
      - Instant Message (IM)
      summary: User Sign-In (IM)
      description: Login a user based using an instant message (IM) to the given phone number
      operationId: SignInOTPInstantMessage
      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: User Sign-In (IM) | OTP
        description: Login a user based using an instant message (IM) to the given phone number
        keywords: api, otp
  /v1/auth/otp/signup-in/im:
    post:
      tags:
      - Instant Message (IM)
      summary: User Sign-In with Auto Sign-Up (IM)
      description: Login a user based using an instant message to the given phone number. If the user does not exist, a new user will be created with the given phone number
      operationId: SignUpOrInOTPInstantMessage
      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: User Sign-In with Auto Sign-Up (IM) | OTP
        description: Login a user based using an instant message to the given phone number. If the user does not exist, a new user will be created with the given phone number
        keywords: api, otp
  /v1/auth/otp/verify/im:
    post:
      tags:
      - Instant Message (IM)
      summary: Verify Code (IM)
      description: Verify a Sign in / Sign up based on an instant message
      operationId: VerifyCodeIM
      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 Code (IM) | OTP
        description: Verify a Sign in / Sign up based on an instant message
        keywords: api, otp
  /v1/auth/otp/update/phone/im:
    post:
      tags:
      - Instant Message (IM)
      summary: Update Phone (IM)
      description: Update phone, and verify via OTP based on an instant message
      operationId: UpdateUserPhoneOTPIM
      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 (IM) | OTP
        description: Update phone, and verify via OTP based on an instant message
        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