Frontegg Data Migration API

openapi: 3.0.0
info:
  title: Multi-Apps Overview Account Invitations Data Migration 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: Data Migration
  x-displayName: Data migration
paths:
  /resources/migrations/v1/auth0:
    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: UsersControllerV1_migrateUserFromAuth0
      summary: Migrate From Auth0
      description: 'Migrate users from Auth0 into your environment.


        Provide the `domain`, `clientId`, `secret`, and `tenantIdFieldName` parameters in the request body. These values can be obtained from your Auth0 account (tenant) configuration.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Auth0Configuration'
      responses:
        '201':
          description: ''
      tags:
      - Data Migration
      security:
      - bearer: []
  /resources/migrations/v1/local:
    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: UsersControllerV1_migrateUserForVendor
      summary: Migrate a Single User
      description: 'Migrate a user into your environment.


        Provide the required fields: user''s email, `tenantId`, and metadata. You can also include additional properties such as the user''s name, phone number, hashed password, and other optional attributes.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrateUserRequestV1'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDto'
      tags:
      - Data Migration
      security:
      - bearer: []
  /resources/migrations/v1/local/bulk:
    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: UsersControllerV1_bulkMigrateUserForVendor
      summary: Migrate Users in Bulk
      description: 'Migrate users in bulk into your environment.


        Provide an array of `users` in the request body. Each user object must include the user''s `email` and `tenantId`, which specifies the user''s parent account. You can include additional fields as needed to store more information. If you need to store custom data, use the `metadata` property.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrateUsersRequestV1'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrationContext'
      tags:
      - Data Migration
      security:
      - bearer: []
  /resources/migrations/v1/local/bulk/status/{migrationId}:
    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
    get:
      operationId: UsersControllerV1_checkBulkMigrationStatus
      summary: Check Status of Bulk Migration
      description: 'Retrieve the status of a pending or completed migration.


        The response includes the migration''s `state`, the number of migrated users, and any errors that occurred during the migration. The response payload is limited to 1,000 users.'
      parameters:
      - name: migrationId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrationObject'
      tags:
      - Data Migration
      security:
      - bearer: []
  /resources/migrations/v2/local/bulk:
    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: UsersControllerV2_bulkMigrateUserForVendor
      summary: Migrate Vendor Users in Bulk
      description: Migrate users in bulk to your environment. Provide an array of user objects, each containing `email` and `tenantId`. Use the `metadata` property to store custom information for each user.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrateUsersRequestV2'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrationContext'
      tags:
      - Data Migration
      security:
      - bearer: []
components:
  schemas:
    UserDto:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        profilePictureUrl:
          type: string
        sub:
          type: string
        verified:
          type: boolean
        mfaEnrolled:
          type: boolean
        mfaBypass:
          type: boolean
        phoneNumber:
          type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/RoleResponse'
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/PermissionResponse'
        provider:
          type: string
        tenantId:
          type: string
        tenantIds:
          type: array
          items:
            type: string
        activatedForTenant:
          type: boolean
        isLocked:
          type: boolean
        tenants:
          type: array
          items:
            $ref: '#/components/schemas/UserTenantDto'
        invisible:
          type: boolean
        superUser:
          type: boolean
        metadata:
          type: string
        vendorMetadata:
          type: string
        externalId:
          type: string
        createdAt:
          format: date-time
          type: string
        lastLogin:
          format: date-time
          type: string
        groups:
          type: array
          items:
            type: object
        subAccountAccessAllowed:
          type: boolean
        managedBy:
          enum:
          - frontegg
          - scim2
          - external
          type: string
      required:
      - id
      - email
      - name
      - profilePictureUrl
      - sub
      - verified
      - mfaEnrolled
      - roles
      - permissions
      - provider
      - tenantId
      - tenantIds
      - tenants
      - metadata
      - vendorMetadata
      - createdAt
      - lastLogin
      - subAccountAccessAllowed
    MigrateUsersRequestV2:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/MigrateUserRequestV2'
      required:
      - users
    UserTenantDto:
      type: object
      properties:
        tenantId:
          type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/RoleResponse'
        temporaryExpirationDate:
          format: date-time
          type: string
        isDisabled:
          type: boolean
      required:
      - tenantId
      - roles
    PhoneNumberType:
      type: string
      enum:
      - auth
      - mfa
    EmailObjectDto:
      type: object
      properties:
        email:
          type: string
          description: The email address
          format: email
        primary:
          type: boolean
          description: Whether this is the primary email
        verified:
          type: boolean
          description: Whether this email is verified
      required:
      - email
      - primary
      - verified
    MigrateUserRequestV1:
      type: object
      properties:
        tenantId:
          type: string
          description: The tenant id of the user
        name:
          type: string
          description: The name of the user
        profilePictureUrl:
          type: string
          description: The profile picture url of the user
          maxLength: 4095
        passwordHash:
          type: string
          description: The password hash. For SCrypt should include the salt and key seperated by the salt separator
        passwordHashType:
          $ref: '#/components/schemas/PasswordHashingType'
        passwordHashConfig:
          type: string
          maxLength: 4095
          description: Stringified JSON Hashing config for the migrated password. For SCrypt should be formatted as { saltSeparator, N, r, p, keyLen }. For FirebaseScrypt should be formatted as { memCost, rounds, saltSeparator, signerKey }
        authenticatorAppMfaSecret:
          type: string
          description: The authenticator app MFA secret
        phoneNumber:
          type: string
          description: 'phoneNumber can be used both for login with SMS and for MFA This auto-enrolls the user in MFA, prompting them at first login (regardless of tenant/vendor MFA settings). The required format is an area code + number, no spaces. For example: "+16037184056" The number must be unique'
        phoneNumberType:
          $ref: '#/components/schemas/PhoneNumberType'
        provider:
          type: string
          enum:
          - local
          - saml
          - google
          - github
          - facebook
          - microsoft
          - scim2
          - slack
          - apple
          default: local
        metadata:
          type: string
          description: Stringified JSON object
        roleIds:
          default: []
          description: Role ids of the migrated users. If not provided, the user will be assigned the default roles
          type: array
          items:
            type: string
        vendorMetadata:
          type: string
          description: Extra vendor-only data. stringified JSON object
        externalId:
          type: string
          description: The external id of the user
        username:
          type: string
          description: The username of the user. If not provided, the email is required. Maximum length is 255 characters.
          maxLength: 128
        email:
          type: string
          description: The email of the user. If not provided, the username is required
        verifyUser:
          type: boolean
          default: false
          description: Whether to verify the user as part of the migration process. If this is set to false, another call is required for the verify user API
      required:
      - tenantId
      - email
    MigrateUsersRequestV1:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/MigrateUserRequestV1'
      required:
      - users
    MigrationObject:
      type: object
      properties: {}
    Auth0Configuration:
      type: object
      properties:
        domain:
          type: string
        clientId:
          type: string
        secret:
          type: string
        tenantIdFieldName:
          type: string
          description: The field name that the tenant ID will be taken from under app metadata
        isTenantIdOnUserMetadata:
          type: boolean
          description: If you would like to take tenant ID from user metadata, set this field to true
      required:
      - domain
      - clientId
      - secret
      - tenantIdFieldName
    PasswordHashingType:
      type: string
      enum:
      - bcrypt
      - scrypt
      - firebase-scrypt
      - pbkdf2
      - argon2
      - sha256
      - sha1
    PermissionResponse:
      type: object
      properties:
        id:
          type: string
        key:
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
        roleIds:
          type: array
          items:
            type: string
        categoryId:
          type: string
        fePermission:
          type: boolean
      required:
      - id
      - key
      - name
      - description
      - createdAt
      - updatedAt
      - roleIds
      - categoryId
      - fePermission
    MigrationContext:
      type: object
      properties:
        migrationId:
          type: string
      required:
      - migrationId
    RoleResponse:
      type: object
      properties:
        id:
          type: string
        vendorId:
          type: string
        tenantId:
          type: string
        key:
          type: string
        name:
          type: string
        description:
          type: string
        isDefault:
          type: boolean
        firstUserRole:
          type: boolean
        level:
          type: number
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
        permissions:
          type: array
          items:
            type: string
      required:
      - id
      - vendorId
      - tenantId
      - key
      - name
      - description
      - isDefault
      - firstUserRole
      - level
      - createdAt
      - updatedAt
      - permissions
    MigrateUserRequestV2:
      type: object
      properties:
        tenantId:
          type: string
          description: The tenant id of the user
        name:
          type: string
          description: The name of the user
        profilePictureUrl:
          type: string
          description: The profile picture url of the user
          maxLength: 4095
        passwordHash:
          type: string
          description: The password hash. For SCrypt should include the salt and key seperated by the salt separator
        passwordHashType:
          $ref: '#/components/schemas/PasswordHashingType'
        passwordHashConfig:
          type: string
          maxLength: 4095
          description: Stringified JSON Hashing config for the migrated password. For SCrypt should be formatted as { saltSeparator, N, r, p, keyLen }. For FirebaseScrypt should be formatted as { memCost, rounds, saltSeparator, signerKey }
        authenticatorAppMfaSecret:
          type: string
          description: The authenticator app MFA secret
        phoneNumber:
          type: string
          description: 'phoneNumber can be used both for login with SMS and for MFA This auto-enrolls the user in MFA, prompting them at first login (regardless of tenant/vendor MFA settings). The required format is an area code + number, no spaces. For example: "+16037184056" The number must be unique'
        phoneNumberType:
          $ref: '#/components/schemas/PhoneNumberType'
        provider:
          type: string
          enum:
          - local
          - saml
          - google
          - github
          - facebook
          - microsoft
          - scim2
          - slack
          - apple
          default: local
        metadata:
          type: string
          description: Stringified JSON object
        roleIds:
          default: []
          description: Role ids of the migrated users. If not provided, the user will be assigned the default roles
          type: array
          items:
            type: string
        vendorMetadata:
          type: string
          description: Extra vendor-only data. stringified JSON object
        externalId:
          type: string
          description: The external id of the user
        username:
          type: string
          description: The username of the user. If not provided, the email is required. Maximum length is 128 characters.
          maxLength: 128
        emails:
          description: The emails of the user. If not provided, the username is required
          type: array
          items:
            $ref: '#/components/schemas/EmailObjectDto'
      required:
      - tenantId
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
x-tagGroups:
- name: Management
  tags:
  - Applications settings