Bulk Migration with Credentials

On This Page

Performing a migration using the Okta API

As part of your plan and preparation to migrate your users to Okta, you gathered your source data into an intermediate staging area such as a secure local database or a CSV file. This guide shows you how to use that data to create users and groups in Okta using the Okta Users API (opens new window) and the Okta Groups API (opens new window).

Prerequisites

To use this guide, you need the following:

Note: The examples in this guide are presented using cURL commands. Postman can generate request code for a number of programming languages that can help with development.

Sample data

The Okta Users API (opens new window) provides several operations to create users. To keep it simple, we’ll use Create User without Credentials (opens new window) in this guide.

This is the sample data we’ll use for one user:

  • First Name: John
  • Last Name: Smith
  • Email Address: john.smith@example.com
  • Groups: All Employees, Sales, Northeast

It’s a good idea to use sample data that’s as close as possible to your real user data to identify any potential issues before implementation.

Create groups

If your user data includes groups and you want to include those groups when you create your users in Okta, you’ll have to create equivalent Okta Groups first. You can create an Okta Group for the sample data we’re using (in this case, “All Employees”) using an Add Group (opens new window) request:

Request example 

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "name": "All Employees",
    "description": "Every single one of our employees"
  }
}' "https://${yourOktaDomain}/api/v1/groups"

The description property can be blank.

Response example 

{
    "id": "00g40q3dfwN2l6Bju357",
    "created": "2020-05-26T21:29:25.000Z",
    "lastUpdated": "2020-05-26T21:29:25.000Z",
    "lastMembershipUpdated": "2020-05-26T21:29:25.000Z",
    "objectClass": [
        "okta:user_group"
    ],
    "type": "OKTA_GROUP",
    "profile": {
        "name": "All Employees",
        "description": "Every single one of our employees"
    },
    "_links": {
        "logo": [
            {
                "name": "medium",
                "href": "https://${yourOktaDomain}/img/logos/groups/okta-medium.png",
                "type": "image/png"
            },
            {
                "name": "large",
                "href": "https://${yourOktaDomain}/img/logos/groups/okta-large.png",
                "type": "image/png"
            }
        ],
        "users": {
            "href": "https://${yourOktaDomain}/api/v1/groups/00g40q3dfwN2l6Bju357/users"
        },
        "apps": {
            "href": "https://${yourOktaDomain}/api/v1/groups/00g40q3dfwN2l6Bju357/apps"
        }
    }
}

You can obtain the new Group ID (id) from the response to use when you create Users in that Group later. You can also list all Groups in your org and obtain their IDs using a List Groups request.

You can also create Groups in your Okta Admin Console. For more information, see Manage groups (opens new window) in the product documentation.

Create users

Once you have created all the necessary Okta Groups, you can create Users including their Group Memberships. As mentioned earlier, we’re using Create User without Credentials to create our sample user. In our sample, the user’s email address is our unique login and the Group IDs are from the List Groups request in the previous step.

Request example with groups 

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "login": "john.smith@example.com"
  },
  "groupIds": [
    "00g40q3dfwN2l6Bju357",
    "00g40qj7v5fn1AcOi357",
    "00g40qkfmol5YWDUX357"
  ]
}' "https://${yourOktaDomain}/api/v1/users?activate=false"

If you don’t have any Groups or want to add your Users to Groups later, simply use the same request but without the groupIds array.

Request example without groups 

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "login": "john.smith@example.com"
  }
}' "https://${yourOktaDomain}/api/v1/users?activate=false"

Response example for both requests 

{
    "id": "00u40qykk8zaeeRfe357",
    "status": "STAGED",
    "created": "2020-05-26T22:33:44.000Z",
    "activated": null,
    "statusChanged": null,
    "lastLogin": null,
    "lastUpdated": "2020-05-26T22:33:44.000Z",
    "passwordChanged": null,
    "type": {
        "id": "oty1lidmn8y5qtJc6357"
    },
    "profile": {
        "firstName": "John",
        "lastName": "Smith",
        "mobilePhone": null,
        "secondEmail": null,
        "login": "john.smith@example.com",
        "email": "john.smith@example.com"
    },
    "credentials": {
        "emails": [
            {
                "value": "john.smith@example.com",
                "status": "VERIFIED",
                "type": "PRIMARY"
            }
        ],
        "provider": {
            "type": "OKTA",
            "name": "OKTA"
        }
    },
    "_links": {
        "schema": {
            "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/osc1lidmn8y5qtJc6357"
        },
        "activate": {
            "href": "https://${yourOktaDomain}/api/v1/users/00u40qykk8zaeeRfe357/lifecycle/activate",
            "method": "POST"
        },
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/users/00u40qykk8zaeeRfe357"
        },
        "type": {
            "href": "https://${yourOktaDomain}/api/v1/meta/types/user/oty1lidmn8y5qtJc6357"
        }
    }
}

User status and activation

The user status in the response when you create a User is set to STAGED, which essentially means that the user has been created but not activated yet. You can activate users using the API or in your Okta Admin Console. For more information on account states and activation, see:

Rate limits

Remember that rate limits (opens new window) apply to API requests when doing bulk/batch user migration, and the rate limits differ depending on the level of service you have purchased from Okta. You can check your rate limits (opens new window) in your code using Okta’s Rate Limit Headers.

Next steps

At this point, you should understand how to use the Okta API to migrate legacy users and groups to Okta.

Your next step should be configuring the necessary integration and access to applications for your users. Be sure to read the product documentation for an overview of application integration (opens new window) and see the information about The Applications Page (opens new window) for more on how to configure your applications.

Reference

This is a collection of reference links that we covered in this guide, as well as links for further information:

API reference pages

Product help pages

Lastly, if you get stuck, don’t hesitate to post a question on the Okta Developer Forum (opens new window).

Edit This Page On GitHub