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:
- An Okta developer org. (Don’t have one? Create an org for free. (opens new window))
- Postman client to run API requests. See Use Postman with the Okta REST APIs (opens new window) 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 (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:
- User status values (opens new window) (API reference)
- Activate User request (opens new window) (API reference)
- End user account states (opens new window) (product documentation)
- Activate user accounts (opens new window) (product documentation)
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
- Okta Users API
- Okta Groups API (opens new window)
- API error codes
- Default user profile properties
- Rate limits
Product help pages
- Get started with Okta (opens new window)
- Profile mastering (opens new window)
- Users, Groups, and Profiles (opens new window)
Lastly, if you get stuck, don’t hesitate to post a question on the Okta Developer Forum (opens new window).