Frontegg Passwordless API

openapi: 3.0.0
info:
  title: Multi-Apps Overview Account Invitations Passwordless API
  description: Frontegg’s Multi-Apps feature simplifies and streamlines application management, delivering a seamless user experience. This section includes all necessary endpoints for managing applications and copying application settings across environments. All endpoints are categorized as **Management Endpoints**, requiring environment-level authorization and providing full control over entitlement resources.
  version: '1.0'
  x-metadata:
    note: Trigger publish artifacts job, remove this x-metadata after publishing
servers:
- url: https://api.frontegg.com/applications
  description: EU Region
- url: https://api.us.frontegg.com/applications
  description: US Region
- url: https://api.ca.frontegg.com/applications
  description: CA Region
- url: https://api.au.frontegg.com/applications
  description: AU Region
- url: https://{domain}.frontegg.com/applications
  description: Frontegg sub-domain for use with user tokens
  variables:
    domain:
      default: app-xxx
tags:
- name: Passwordless
  x-displayName: Passwordless
paths:
  /resources/auth/v1/passwordless/smscode/prelogin:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: AuthenticationPasswordlessControllerV1_smsCodePreLogin
      summary: SMS Code Prelogin
      description: 'Initiate SMS-based passwordless authentication by sending a one-time code (OTC) to the user''s phone.


        This is the first step in the SMS OTC passwordless login flow. The system sends an SMS to the user associated with the provided email address.


        Request body must include:

        - `email`: The email address of the user initiating the login.

        - `invitationToken` (optional): Include if the user is signing up through an invitation.

        - `recaptchaToken` (optional): Required if reCAPTCHA is enabled for login.


        Use this endpoint to begin the passwordless login process using SMS verification.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordlessAuthenticationSmsOtcPreloginDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordlessAuthenticationSmsOTCPreloginResponseDto'
        '400':
          description: User does not have a phone number
      tags:
      - Passwordless
      security:
      - bearer: []
  /resources/auth/v1/passwordless/smscode/postlogin:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: AuthenticationPasswordlessControllerV1_smsCodePostLogin
      summary: SMS Code Postlogin
      description: 'Complete passwordless authentication using a one-time code (OTC) sent via SMS.


        This is the second step in the SMS OTC passwordless login flow. After the user receives the code, this endpoint finalizes authentication and returns a valid JWT and refresh cookie.


        Request body must include:

        - `token`: The token ID associated with the SMS OTC sent to the user.

        - `invitationToken` (optional): Include if the user is signing up through an invitation.

        - `recaptchaToken` (optional): Required if reCAPTCHA is enabled for login.


        Use this endpoint to complete passwordless login via SMS and receive authentication tokens for the session.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateUserPasswordlessDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponseDto'
      tags:
      - Passwordless
      security:
      - bearer: []
  /resources/auth/v1/passwordless/magiclink/prelogin:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: AuthenticationPasswordlessControllerV1_magicLinkPrelogin
      summary: Magic Link Prelogin
      description: 'Initiate passwordless authentication by sending a magic link to the user''s email address.


        This is the first step in the magic link passwordless login flow for local users. The system sends an email containing a secure login link to the provided address.


        Request body must include:

        - `email`: The email address of the user initiating the login.

        - `invitationToken` (optional): Include if the user is signing up through an invitation.

        - `recaptchaToken` (optional): Required if reCAPTCHA is enabled for login.


        Use this endpoint to start the magic link authentication process by delivering a login link to the user''s email inbox.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordlessAuthenticationPreloginDto'
      responses:
        '200':
          description: ''
        '400':
          description: Invalid authentication type, magic link authentication should be enabled
      tags:
      - Passwordless
      security:
      - bearer: []
  /resources/auth/v1/passwordless/magiclink/postlogin:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: AuthenticationPasswordlessControllerV1_magicLinkPostLogin
      summary: Magic Link Postlogin
      description: 'Complete passwordless authentication using a magic link.


        This is the second step in the magic link passwordless login flow for local users. After the user clicks the link in their email, this endpoint validates the token and authenticates the user.


        Request body must include:

        - `token`: The token ID extracted from the magic link.

        - `invitationToken` (optional): Include if the user is signing up through an invitation.

        - `recaptchaToken` (optional): Required if reCAPTCHA is enabled for login.


        Use this endpoint to complete the magic link login flow and receive authentication credentials, including a JWT and a refresh cookie.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateUserPasswordlessDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponseDto'
      tags:
      - Passwordless
      security:
      - bearer: []
  /resources/auth/v1/passwordless/code/prelogin:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: AuthenticationPasswordlessControllerV1_emailCodePrelogin
      summary: OTC (One-Time Code) Prelogin
      description: 'Initiate passwordless authentication by sending a one-time code (OTC) to the user''s email address.


        This is the first step in the email OTC (one-time code) passwordless login flow for local users. The system sends a time-sensitive code to the specified email address.


        Request body must include:

        - `email`: The email address of the user initiating the login.

        - `invitationToken` (optional): Include if the user is signing up through an invitation.

        - `recaptchaToken` (optional): Required if reCAPTCHA is enabled for login.


        Use this endpoint to start the passwordless login process via an email-based one-time code.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordlessAuthenticationPreloginDto'
      responses:
        '201':
          description: ''
        '400':
          description: Invalid authentication type, OTC (One-Time Code) authentication should be enabled
      tags:
      - Passwordless
      security:
      - bearer: []
  /resources/auth/v1/passwordless/code/postlogin:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: AuthenticationPasswordlessControllerV1_emailCodePostLogin
      summary: OTC (One-Time Code) Postlogin
      description: 'Complete passwordless authentication using a one-time code (OTC) sent to the user''s email.


        This is the second step in the email OTC passwordless login flow. After the user receives and enters the code, this endpoint validates the token and finalizes authentication.


        Request body must include:

        - `token`: The token ID associated with the email OTC sent to the user.

        - `invitationToken` (optional): Include if the user is signing up via an invitation.

        - `recaptchaToken` (optional): Required if reCAPTCHA is enabled for login.


        Use this endpoint to validate the email-based one-time code and receive authentication credentials, including a JWT and refresh cookie.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateUserPasswordlessDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponseDto'
      tags:
      - Passwordless
      security:
      - bearer: []
components:
  schemas:
    UserMFAPhoneDeviceResponse:
      type: object
      properties:
        id:
          type: string
        phoneNumber:
          type: string
      required:
      - id
      - phoneNumber
    UserMFADevicesResponse:
      type: object
      properties:
        webauthn:
          type: array
          items:
            $ref: '#/components/schemas/UserMFAWebAuthnDeviceResponse'
        phones:
          type: array
          items:
            $ref: '#/components/schemas/UserMFAPhoneDeviceResponse'
        authenticators:
          type: array
          items:
            $ref: '#/components/schemas/UserMFAAuthenticatorAppResponse'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/UserMFAEmailCodeResponse'
      required:
      - webauthn
      - phones
      - authenticators
      - emails
    UserMFAWebAuthnDeviceResponse:
      type: object
      properties:
        id:
          type: string
        deviceType:
          type: string
          enum:
          - Platform
          - CrossPlatform
        name:
          type: string
      required:
      - id
      - deviceType
      - name
    AuthenticationResponseDto:
      type: object
      properties:
        tokenType:
          type: string
          default: bearer
        otcToken:
          type: string
        mfaRequired:
          type: boolean
        mfaToken:
          type: string
        resetPasswordToken:
          type: string
        passwordExpiresIn:
          type: number
        notificationPeriod:
          type: number
        mfaEnrolled:
          type: boolean
        mfaDevices:
          $ref: '#/components/schemas/UserMFADevicesResponse'
        mfaStrategies:
          type: object
        qrCode:
          type: string
        recoveryCode:
          type: string
        accessToken:
          type: string
        refreshToken:
          type: string
        expiresIn:
          type: number
        expires:
          type: string
        userId:
          type: string
        userEmail:
          type: string
        emailVerified:
          type: boolean
        isBreachedPassword:
          type: boolean
      required:
      - mfaRequired
      - accessToken
      - refreshToken
      - expiresIn
      - expires
    UserMFAAuthenticatorAppResponse:
      type: object
      properties:
        id:
          type: string
      required:
      - id
    AuthenticateUserPasswordlessDto:
      type: object
      properties:
        token:
          type: string
          description: One time code to login with - get it from the email sent after prelogin request
        recaptchaToken:
          type: string
        invitationToken:
          type: string
      required:
      - token
    UserMFAEmailCodeResponse:
      type: object
      properties:
        email:
          type: string
      required:
      - email
    PasswordlessAuthenticationSmsOTCPreloginResponseDto:
      type: object
      properties:
        phoneNumber:
          type: string
        resetPhoneNumberToken:
          type: string
    PasswordlessAuthenticationPreloginDto:
      type: object
      properties:
        recaptchaToken:
          type: string
        invitationToken:
          type: string
        email:
          type: string
        userId:
          type: string
        username:
          type: string
      required:
      - email
      - userId
      - username
    PasswordlessAuthenticationSmsOtcPreloginDto:
      type: object
      properties:
        recaptchaToken:
          type: string
        invitationToken:
          type: string
        email:
          type: string
        userId:
          type: string
        username:
          type: string
        phoneNumber:
          type: string
      required:
      - email
      - userId
      - username
      - phoneNumber
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
x-tagGroups:
- name: Management
  tags:
  - Applications settings