openapi: 3.0.3
info:
  title: Descope Apps Verification 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: Verification
paths:
  /v1/auth/magiclink/verify:
    post:
      tags:
      - Verification
      summary: Verify Token
      description: "### Verify the magic link token from the end user\n\nVerify that the magic link token in the URL clicked by the end user matches and has not expired. This endpoint completes the magic link flow for:\n* sign up\n    * [Sign-Up via email](/api/magic-link/email/sign-up)\n    * [Sign-Up via SMS](/api/magic-link/sms/sign-up)\n* sign-in\n    * [Sign-In via email](/api/magic-link/email/sign-in)\n    * [Sign-In via SMS](/api/magic-link/sms/sign-in)\n* sign-in with auto sign-up\n    * [Sign-In with Auto Sign-up via email](/api/magic-link/email/sign-in-auto-sign-up)\n    * [Sign-In with Auto Sign-up via SMS](/api/magic-link/sms/sign-in-auto-sign-up)\n* update data\n    * [update email](/api/magic-link/email/sign-up)\n    * [update phone number](/api/magic-link/email/sign-up)\n\n### Next Steps\n\nThe response object will contain the user's details including the session and refresh JWTs.\n\n### See Also\n- See [Magic link Authentication](/auth-methods/magic-link/with-sdks/client#introduction) for details about implementing magic links.\n- 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: VerifyMagicLink
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyMagicLinkRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
      security:
      - Descope Project ID: []
      x-publishYaml: MagicLink
      x-order: 1
      x-meta:
        title: Verify Token | Magic Link
        description: Verify the magic link token from the end user
        keywords: api, magic link
components:
  schemas:
    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
    UserTenants:
      type: object
      properties:
        tenantId:
          type: string
        roleNames:
          type: array
          items:
            type: string
        tenantName:
          type: string
        permissions:
          type: array
          items:
            type: string
    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'
    VerifyMagicLinkRequest:
      type: object
      properties:
        token:
          type: string
    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