Bulk Migration with Credentials

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 and the Okta Groups API.

Prerequisites

To use this guide, you need the following:

• An Okta developer org. (Don’t have one? Create an org for free.)
• Postman client to run API requests. See Use Postman with the Okta REST APIs for information on setting up Postman.
• Example or test source data to test user and group creation requests. (Do not use real user data when testing!)

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 provides several operations to create users. To keep it simple, we’ll use Create User without Credentials 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 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 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:

• User status values (API reference)
• Activate User request (API reference)
• End user account states (product documentation)
• Activate user accounts (product documentation)

Rate limits

Remember that rate limits 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 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 and see the information about The Applications Page 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

• Okta Users API
• Okta Groups API
• API error codes
• Default user profile properties
• Rate limits

Product help pages

• Get started with Okta
• Profile mastering
• Users, Groups, and Profiles

Lastly, if you get stuck, don’t hesitate to post a question in our Developer Forums.