Frontegg Data Migration API

openapi: 3.2.0
info:
  title: Entitlements Agent (PDP) Data Migration API
  description: 'The endpoints in this section pertain to the usage of an Entitlements Agent. When your application or service needs to verify entitlements, it can query the Entitlements Agent directly via HTTP.


    These endpoints can be integrated into any backend framework, enabling you to leverage entitlements for advanced authorization needs.'
  version: '1.0'
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:
    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
    PhoneNumberType:
      type: string
      enum:
      - auth
      - mfa
    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
    MigrationObject:
      type: object
      properties: {}
    MigrationContext:
      type: object
      properties:
        migrationId:
          type: string
      required:
      - migrationId
    MigrateUsersRequestV1:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/MigrateUserRequestV1'
      required:
      - users
    MigrateUsersRequestV2:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/MigrateUserRequestV2'
      required:
      - users
    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
    PasswordHashingType:
      type: string
      enum:
      - bcrypt
      - scrypt
      - firebase-scrypt
      - pbkdf2
      - argon2
      - sha256
      - sha1
    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
    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
    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
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
x-tagGroups:
- name: Entitlements Agent (PDP)
  tags:
  - Entitlements Check
- name: Audits Overview
  tags:
  - Main
  - Metrics
- name: Entitlements Overview
  tags:
  - Plans
  - API Access Control
  - API Access Control Configurations
  - Features
  - Entitlements
  - Feature Flags
  - ReBAC
- name: Authentication and Identity Management
  tags:
  - API token
  - API tokens
  - Account invitations
  - Account invitations settings
  - Account roles
  - Approval Flows
  - Core settings
  - Custom social OAuth provider
  - Data migration
  - Delegation
  - Domain restrictions
  - Email configuration
  - Email templates
  - General
  - IP restrictions
  - Lockout policy
  - M2M tokens
  - MFA
  - MFA configuration
  - MFA settings
  - Password settings
  - Passwordless
  - Permissions
  - Permissions categories
  - Personal tokens
  - Roles
  - SMS
  - SMS configuration
  - SMS templates
  - Sessions configuration
  - Sessions management
  - User emails policy
  - User groups
  - User management
  - Users
  - User pools
  - User sessions
  - Users-applications management
- name: SCIM Provisioning Overview
  tags:
  - SCIM settings
  - SCIM configurations
- name: Single Sign-On Overview
  tags:
  - SAML configurations
  - SSO settings
  - SSO configurations
  - OIDC configurations
- name: Account Management Overview
  tags:
  - Accounts
  - tenants_other
  - Sub-accounts
  - Account settings
  - Account migration
  - Sub-accounts and hierarchy