Users API

The Okta User API provides operations to manage users in your organization.

Getting Started

Explore the Users API:

User Operations

Create User

POST /api/v1/users

Creates a new user in your Okta organization with or without credentials

Create User without Credentials
Create User with Recovery Question
Create User with Password
Create User with Imported Hashed Password
Create User with Password & Recovery Question
Create User with Authentication Provider
Create User in Group

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
activate	Executes activation lifecycle operation when creating the user	Query	Boolean	FALSE	TRUE
provider	Indicates whether to create a user with a specified authentication provider	Query	Boolean	FALSE	FALSE
profile	Profile properties for user	Body	Profile Object	TRUE
credentials	Credentials for user	Body	Credentials Object	FALSE
groupIds	Ids of groups that user will be immediately added to at time of creation	Body	Array of Group Ids	FALSE
nextLogin	With `activate=true`, if `nextLogin=changePassword`, a user is created, activated, and the password is set to `EXPIRED`, so user must change it the next time they log in.	Query	String	FALSE	FALSE

Response Parameters

All responses return the created User. Activation of a user is an asynchronous operation. The system performs group reconciliation during activation and assigns the user to all applications via direct or indirect relationships (group memberships).

The user's transitioningToStatus property is ACTIVE during activation to indicate that the user hasn't completed the asynchronous operation.
The user's status is ACTIVE when the activation process is complete.

The user is emailed a one-time activation token if activated without a password.

Note: If the user is assigned to an application that is configured for provisioning, the activation process triggers downstream provisioning to the application. It is possible for a user to login before these applications have been successfully provisioned for the user.

Security Q & A	Password	Activate Query Parameter	User Status	Login Credential	Welcome Screen
		FALSE	`STAGED`
		TRUE	`PROVISIONED`	One-Time Token (Email)	X
X		FALSE	`STAGED`
X		TRUE	`PROVISIONED`	One-Time Token (Email)	X
	X	FALSE	`STAGED`
	X	TRUE	`ACTIVE`	Password	X
X	X	FALSE	`STAGED`
X	X	TRUE	`ACTIVE`	Password

Creating users with a FEDERATION or SOCIAL provider sets the user status to either ACTIVE or STAGED based on the activate query parameter since these two providers don't support a password or recovery_question credential.

Create User without Credentials

Creates a user without a password or recovery question & answer

When the user is activated, an email is sent to the user with an activation token that can be used to complete the activation process. This is the default flow for new user registration using the administrator UI.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  }
}' "https://{yourOktaDomain}/api/v1/users?activate=false"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "STAGED",
  "created": "2013-07-02T21:36:25.344Z",
  "activated": null,
  "statusChanged": null,
  "lastLogin": null,
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": null,
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate"
    }
  }
}

Create User with Recovery Question

Creates a user without a password

When the user is activated, an email is sent to the user with an activation token that can be used to complete the activation process. This flow is useful if migrating users from an existing user store.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "recovery_question": {
      "question": "Who'\''s a major player in the cowboy scene?",
      "answer": "Annie Oakley"
    }
  }
}' "https://{yourOktaDomain}/api/v1/users?activate=false"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "STAGED",
  "created": "2013-07-02T21:36:25.344Z",
  "activated": null,
  "statusChanged": null,
  "lastLogin": null,
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": null,
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate"
    }
  }
}

Create User with Password

Creates a user without a recovery question & answer

The new user is able to login immediately after activation with the assigned password. This flow is common when developing a custom user registration experience.

Important: Do not generate or send a one-time activation token when activating users with an assigned password. Users should login with their assigned password.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password" : { "value": "tlpWENT2m" }
  }
}' "https://{yourOktaDomain}/api/v1/users?activate=false"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "STAGED",
  "created": "2013-07-02T21:36:25.344Z",
  "activated": null,
  "statusChanged": null,
  "lastLogin": null,
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate"
    }
  }
}

Create User with Imported Hashed Password

Creates a user with a specified hashed password.

The new user is able to login immediately after activation with the specified password. This flow is common when migrating users from another data store in cases where we wish to allow the users to retain their current passwords.

Important: Do not generate or send a one-time activation token when activating users with an imported password. Users should login with their imported password.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password" : {
      "hash": {
        "algorithm": "BCRYPT",
        "workFactor": 10,
        "salt": "rwh3vH166HCH/NT9XV5FYu",
        "value": "qaMqvAPULkbiQzkTCWo5XDcvzpk8Tna"
      }
    }
  }
}' "https://{yourOktaDomain}/api/v1/users?activate=false"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-07-02T21:36:25.344Z",
  "activated": null,
  "statusChanged": null,
  "lastLogin": null,
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "provider": {
      "type": "IMPORT",
      "name": "IMPORT"
    }
  },
  "_links": {
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate"
    }
  }
}

Create User with Password & Recovery Question

Creates a new user with a password and recovery question & answer

The new user is able to log in with the assigned password immediately after activation. This flow is common when developing a custom user-registration experience.

Important: Don't generate or send a one-time activation token when activating users with an assigned password. Users should login with their assigned password.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password" : { "value": "tlpWENT2m" },
    "recovery_question": {
      "question": "Who'\''s a major player in the cowboy scene?",
      "answer": "Annie Oakley"
    }
  }
}' "https://{yourOktaDomain}/api/v1/users?activate=false"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "STAGED",
  "created": "2013-07-02T21:36:25.344Z",
  "activated": null,
  "statusChanged": null,
  "lastLogin": null,
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate"
    }
  }
}

Create User with Authentication Provider

Creates a new passwordless user with a SOCIAL or FEDERATION authentication provider that must be authenticated via a trusted Identity Provider

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "provider": {
      "type": "FEDERATION",
      "name": "FEDERATION"
    }
  }
}' "https://{yourOktaDomain}/api/v1/users?provider=true"

Response Example

{
  "id": "00uijntSwJjSHtDY70g3",
  "status": "ACTIVE",
  "created": "2016-01-19T22:02:08.000Z",
  "activated": "2016-01-19T22:02:08.000Z",
  "statusChanged": "2016-01-19T22:02:08.000Z",
  "lastLogin": null,
  "lastUpdated": "2016-01-19T22:02:08.000Z",
  "passwordChanged": null,
  "profile": {
    "login": "isaac.brock@example.com",
    "firstName": "Isaac",
    "lastName": "Brock",
    "mobilePhone": "555-415-1337",
    "email": "isaac.brock@example.com",
    "secondEmail": null
  },
  "credentials": {
    "provider": {
      "type": "FEDERATION",
      "name": "FEDERATION"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00uijntSwJjSHtDY70g3/lifecycle/reset_password",
      "method": "POST"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00uijntSwJjSHtDY70g3/credentials/change_recovery_question",
      "method": "POST"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00uijntSwJjSHtDY70g3/lifecycle/deactivate",
      "method": "POST"
    }
  }
}

Create User in Group

Creates a user that is immediately added to the specified groups upon creation

Use this in conjunction with other create operations for a Group Administrator that is scoped to create users only in specified groups. The request may specify up to 20 group ids. (This limit applies only when creating a user. The user may later be added to more groups.)

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "groupIds": [
    "00g1emaKYZTWRYYRRTSK",
    "00garwpuyxHaWOkdV0g4"
  ]
}' "https://{yourOktaDomain}/api/v1/users?activate=false"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "STAGED",
  "created": "2013-07-02T21:36:25.344Z",
  "activated": null,
  "statusChanged": null,
  "lastLogin": null,
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": null,
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate"
    }
  }
}

Get User

GET /api/v1/users/${userId}

CORS

Fetches a user from your Okta organization

Get Current User
Get User with ID
Get User with Login
Get User with Login Shortname

Request Parameters

Fetch a user by id, login, or login shortname if the short name is unambiguous.

Parameter	Description	Param Type	DataType	Required
id	`id`, `login`, or login shortname (as long as it is unambiguous)	URL	String	TRUE

When fetching a user by login or login shortname, you should URL encode the request parameter to ensure special characters are escaped properly. Logins with a / or ? character can only be fetched by id due to URL issues with escaping the / and ? characters.

Hint: you can substitute me for the id to fetch the current user linked to an API token or session cookie.

Response Parameters

Fetched User

An invalid id returns a 404 Not Found status code.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "errorCode": "E0000007",
    "errorSummary": "Not found: Resource not found: missing@example.com (User)",
    "errorLink": "E0000007",
    "errorId": "oaewgzWY_IaSs6G8Cf2TzzIsA",
    "errorCauses": []
}

Get Current User

Fetches the current user linked to API token or session cookie

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/me"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

Get User with ID

Fetches a specific user when you know the user's id

Hint: If you don't know the user id, list the users to find the correct ID.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

Fetches a specific user when you know the user's login

When fetching a user by login, URL encode the request parameter to ensure special characters are escaped properly. Logins with a / character can only be fetched by id due to URL issues with escaping the / character.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/isaac.brock@example.com"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

Fetches a specific user when you know the user's login shortname and the shortname is unique within the organization

When fetching a user by login shortname, URL encode the request parameter to ensure special characters are escaped properly. Logins with a / character can only be fetched by id due to URL issues with escaping the / character.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/isaac.brock"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

List Users

GET /api/v1/users

Lists users in your organization with pagination in most cases

A subset of users can be returned that match a supported filter expression or search criteria.

Request Parameters

The first three parameters correspond to different types of lists:

List All Users (no parameters)
Find Users (q)
List Users with a Filter (filter)
List Users with Search (search)

Parameter	Description	Param Type	DataType	Required
q	Finds a user that matches `firstName`, `lastName`, and `email` properties	Query	String	FALSE
filter	Filters users with a supported expression for a subset of properties	Query	String	FALSE
search	Searches for users with a supported filtering expression for most properties	Query	String	FALSE
limit	Specifies the number of results returned (maximum 200)	Query	Number	FALSE
after	Specifies the pagination cursor for the next page of users	Query	String	FALSE

If you don't specify a value for limit, the maximum (200) is used as a default. If you are using a q parameter, the default limit is 10.
An HTTP 500 status code usually indicates that you have exceeded the request timeout. Retry your request with a smaller limit and paginate the results. For more information, see Pagination.
Treat the after cursor as an opaque value and obtain it through the next link relation. See Pagination.

Response Parameters

Array of User

List All Users

Returns a list of all users that do not have a status of DEPROVISIONED, up to the maximum (200 for most orgs)

Different results are returned depending on specified queries in the request.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users?limit=200"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://{yourOktaDomain}/api/v1/users?limit=200>; rel="self"
Link: <https://{yourOktaDomain}/api/v1/users?after=00ud4tVDDXYVKPXKVLCO&limit=200>; rel="next"

[
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "STAGED",
    "created": "2013-07-02T21:36:25.344Z",
    "activated": null,
    "statusChanged": null,
    "lastLogin": null,
    "lastUpdated": "2013-07-02T21:36:25.344Z",
    "passwordChanged": "2013-07-02T21:36:25.344Z",
    "profile": {
      "firstName": "Isaac",
      "lastName": "Brock",
      "email": "isaac.brock@example.com",
      "login": "isaac.brock@example.com",
      "mobilePhone": "555-415-1337"
    },
    "credentials": {
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"
      }
    }
  },
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "ACTIVE",
    "created": "2013-06-24T16:39:18.000Z",
    "activated": "2013-06-24T16:39:19.000Z",
    "statusChanged": "2013-06-24T16:39:19.000Z",
    "lastLogin": "2013-06-24T17:39:19.000Z",
    "lastUpdated": "2013-07-02T21:36:25.344Z",
    "passwordChanged": "2013-07-02T21:36:25.344Z",
    "profile": {
      "firstName": "Eric",
      "lastName": "Judy",
      "email": "eric.judy@example.com",
      "secondEmail": "eric@example.org",
      "login": "eric.judy@example.com",
      "mobilePhone": "555-415-2011"
    },
    "credentials": {
      "password": {},
      "recovery_question": {
        "question": "The stars are projectors?"
      },
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"
      }
    }
  }
]

Find Users

Finds users who match the specified query

Use the q parameter for a simple lookup of users by name, for example when creating a people picker. The value of q is matched against firstName, lastName, or email.

This operation:

Doesn't support pagination.
Queries the most up-to-date data. For example, if you create a user or change an attribute and then issue a filter request, the change is reflected in the results.
Performs a startsWith match but this is an implementation detail and may change without notice. You don't need to specify firstName, lastName, or email.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users?q=eric&limit=1"

Response Example

[
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "ACTIVE",
    "created": "2013-06-24T16:39:18.000Z",
    "activated": "2013-06-24T16:39:19.000Z",
    "statusChanged": "2013-06-24T16:39:19.000Z",
    "lastLogin": "2013-06-24T17:39:19.000Z",
    "lastUpdated": "2013-07-02T21:36:25.344Z",
    "passwordChanged": "2013-07-02T21:36:25.344Z",
    "profile": {
      "firstName": "Eric",
      "lastName": "Judy",
      "email": "eric.judy@example.com",
      "secondEmail": "eric@example.org",
      "login": "eric.judy@example.com",
      "mobilePhone": "555-415-2011"
    },
    "credentials": {
      "password": {},
      "recovery_question": {
        "question": "The stars are projectors?"
      },
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"
      }
    }
  }
]

Note: This omits users that have a status of DEPROVISIONED. To return all users, use a filter query instead.

List Users with a Filter

Lists all users that match the filter criteria

This operation:

Filters against the most up-to-date data. For example, if you create a user or change an attribute and then issue a filter request, the changes are reflected in your results.
Requires URL encoding. For example, filter=lastUpdated gt "2013-06-01T00:00:00.000Z" is encoded as filter=lastUpdated%20gt%20%222013-06-01T00:00:00.000Z%22. Examples use cURL-style escaping instead of URL encoding to make them easier to read.
Supports only a limited number of properties: status, lastUpdated, id, profile.login, profile.email, profile.firstName, and profile.lastName.

Filter	Description
`status eq "STAGED"`	Users that have a `status` of `STAGED`
`status eq "PROVISIONED"`	Users that have a `status` of `PROVISIONED`
`status eq "ACTIVE"`	Users that have a `status` of `ACTIVE`
`status eq "RECOVERY"`	Users that have a `status` of `RECOVERY`
`status eq "PASSWORD_EXPIRED"`	Users that have a `status` of `PASSWORD_EXPIRED`
`status eq "LOCKED_OUT"`	Users that have a `status` of `LOCKED_OUT`
`status eq "DEPROVISIONED"`	Users that have a `status` of `DEPROVISIONED`
`lastUpdated lt "yyyy-MM-dd'T'HH:mm:ss.SSSZ"`	Users last updated before a specific timestamp
`lastUpdated eq "yyyy-MM-dd'T'HH:mm:ss.SSSZ"`	Users last updated at a specific timestamp
`lastUpdated gt "yyyy-MM-dd'T'HH:mm:ss.SSSZ"`	Users last updated after a specific timestamp
`id eq "00u1ero7vZFVEIYLWPBN"`	Users with a specified `id`
`profile.login eq "login@example.com"`	Users with a specified `login`
`profile.email eq "email@example.com"`	Users with a specified `email`*
`profile.firstName eq "John"`	Users with a specified `firstName`*
`profile.lastName eq "Smith"`	Users with a specified `lastName`*

Hint: If filtering by email, lastName, or firstName, it may be easier to use q instead of filter.

See Filtering for more information about the expressions used in filtering.

Filter Examples

List users with status of LOCKED_OUT

filter=status eq "LOCKED_OUT"

List users updated after 06/01/2013 but before 01/01/2014

filter=lastUpdated gt "2013-06-01T00:00:00.000Z" and lastUpdated lt "2014-01-01T00:00:00.000Z"

List users updated after 06/01/2013 but before 01/01/2014 with a status of ACTIVE

filter=lastUpdated gt "2013-06-01T00:00:00.000Z" and lastUpdated lt "2014-01-01T00:00:00.000Z" and status eq "ACTIVE"

List users updated after 06/01/2013 but with a status of LOCKED_OUT or RECOVERY

filter=lastUpdated gt "2013-06-01T00:00:00.000Z" and (status eq "LOCKED_OUT" or status eq "RECOVERY")

Request Example: Status

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users?filter=status+eq+\"ACTIVE\"+or+status+eq+\"RECOVERY\""

Response Example

[
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "ACTIVE",
    "created": "2013-06-24T16:39:18.000Z",
    "activated": "2013-06-24T16:39:19.000Z",
    "statusChanged": "2013-06-24T16:39:19.000Z",
    "lastLogin": "2013-06-24T17:39:19.000Z",
    "lastUpdated": "2013-07-02T21:36:25.344Z",
    "passwordChanged": "2013-07-02T21:36:25.344Z",
    "profile": {
      "firstName": "Eric",
      "lastName": "Judy",
      "email": "eric.judy@example.com",
      "secondEmail": "eric@example.org",
      "login": "eric.judy@example.com",
      "mobilePhone": "555-415-2011"
    },
    "credentials": {
      "password": {},
      "recovery_question": {
        "question": "The stars are projectors?"
      },
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"
      }
    }
  }
]

Request Example: Timestamp

Lists all users that have been updated since a specific timestamp

Use this operation when implementing a background synchronization job and you want to poll for changes.

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users?filter=lastUpdated+gt+\"2013-07-01T00:00:00.000Z\""

Response Example

[
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "ACTIVE",
    "created": "2013-06-24T16:39:18.000Z",
    "activated": "2013-06-24T16:39:19.000Z",
    "statusChanged": "2013-06-24T16:39:19.000Z",
    "lastLogin": "2013-06-24T17:39:19.000Z",
    "lastUpdated": "2013-07-02T21:36:25.344Z",
    "passwordChanged": "2013-07-02T21:36:25.344Z",
    "profile": {
      "firstName": "Eric",
      "lastName": "Judy",
      "email": "eric.judy@example.com",
      "secondEmail": "eric@example.org",
      "login": "eric.judy@example.com",
      "mobilePhone": "555-415-2011"
    },
    "credentials": {
      "password": {},
      "recovery_question": {
        "question": "The stars are projectors?"
      },
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"
      }
    }
  }
]

List Users with Search

Listing users with search should not be used as a part of any critical flows, like authentication.

Searches for users based on the properties specified in the search parameter (case insensitive)

This operation:

Supports pagination (to a maximum of 50000 results; see note below).
Requires URL encoding. For example, search=profile.department eq "Engineering" is encoded as search=profile.department%20eq%20%22Engineering%22. Examples use cURL-style escaping instead of URL encoding to make them easier to read.
Queries data from a replicated store, so changes aren't always immediately available in search results. Don't use search results directly for record updates, as the data might be stale and therefore overwrite newer data (data loss). Use an ID lookup for records that you update to ensure your results contain the latest data.
Searches many properties:
- Any user profile property, including custom-defined properties
- The top-level properties id, status, created, activated, statusChanged and lastUpdated

Search Term Example	Description
`status eq "STAGED"`	Users that have a `status` of `STAGED`
`lastUpdated gt "yyyy-MM-dd'T'HH:mm:ss.SSSZ"`	Users last updated after a specific timestamp
`id eq "00u1ero7vZFVEIYLWPBN"`	Users with a specified `id`
`profile.department eq "Engineering"`	Users that have a `department` of `Engineering`
`profile.occupation eq "Leader"`	Users that have an `occupation` of `Leader`
`profile.lastName sw "Sm"`	Users whose `lastName` starts with "Sm

When paginating a search result set (see Pagination), the result set is limited to a total of 50,000 results. Attempting to follow the next link from the last page will yield an error.

Search Examples

List users with an occupation of Leader

search=profile.occupation eq "Leader"

List users in the department of Engineering who were created before 01/01/2014 or have a status of ACTIVE.

search=profile.department eq "Engineering" and (created lt "2014-01-01T00:00:00.000Z" or status eq "ACTIVE")

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users?search=profile.mobilePhone+sw+\"555\"+and+status+eq+\"ACTIVE\""

Response Example

[
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "ACTIVE",
    "created": "2013-06-24T16:39:18.000Z",
    "activated": "2013-06-24T16:39:19.000Z",
    "statusChanged": "2013-06-24T16:39:19.000Z",
    "lastLogin": "2013-06-24T17:39:19.000Z",
    "lastUpdated": "2013-07-02T21:36:25.344Z",
    "passwordChanged": "2013-07-02T21:36:25.344Z",
    "profile": {
      "firstName": "Isaac",
      "lastName": "Brock",
      "email": "isaac.brock@example.com",
      "login": "isaac.brock@example.com",
      "mobilePhone": "555-415-1337"
    },
    "credentials": {
      "password": {},
      "recovery_question": {
        "question": "Who's a major player in the cowboy scene?"
      },
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"
      }
    }
  }
]

Searching Arrays

You can search properties that are arrays. If any element matches the search term, the entire array (object) is returned. For examples, see Request Example for Array and Response Example for Array.

We follow the SCIM Protocol Specification for searching arrays.
Search for one value at a time when searching arrays. For example, you can't search for users where a string is equal to an attribute in two different arrays.

Request Example for Array

The following example is for a custom attribute on User, an array of strings named arrayAttr that contains values ["arrayAttrVal1", "arrayAttrVal2"...].

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users?search=profile.arrayAttr+eq+\"arrayAttrVal1\" "

Response Example for Array

[
    {
        "id": "00u19uiKQa0xXkbdGLNR",
        "status": "PROVISIONED",
        "created": "2016-03-15T04:21:51.000Z",
        "activated": "2016-03-15T04:21:52.000Z",
        "statusChanged": "2016-03-15T04:21:52.000Z",
        "lastLogin": null,
        "lastUpdated": "2016-03-17T07:08:15.000Z",
        "passwordChanged": null,
        "profile": {
            "login": "u7@test.com",
            "mobilePhone": null,
            "email": "u7@test.com",
            "secondEmail": "",
            "firstName": "u7",
            "lastName": "u7",
            "boolAttr": true,
            "intAttr": 99,
            "strArray": [
                "strArrayVal1",
                "strArrayVal2"
            ],
            "intArray": [
                5,
                8
            ],
            "numAttr": 8.88,
            "attr1": "attr1ValUpdated3",
            "arrayAttr": [
                "arrayAttrVal1",
                "arrayAttrVal2Updated"
            ],
            "numArray": [
                1.23,
                4.56
            ]
        },
        "credentials": {
            "provider": {
                "type": "OKTA",
                "name": "OKTA"
            }
        },
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u19uiKQa0xXkbdGLNR"
            }
        }
    }
]

Update User

Note: Use the POST method to make a partial update and the PUT method to delete unspecified properties.

PUT /api/v1/users/${userId}

Updates a user's profile and/or credentials using strict-update semantics

All profile properties must be specified when updating a user's profile with a PUT method. Any property not specified in the request is deleted.

Important: Don't use PUT method for partial updates.

Request Parameters

Parameter	Description	Param Type	DataType	Required
userId	ID of user to update	URL	String	TRUE
strict	If true, validates against minimum age and history password policy	Query	String	FALSE
profile	Updated profile for user	Body	Profile Object	FALSE
credentials	Update credentials for user	Body	Credentials Object	FALSE

profile and credentials can be updated independently or together with a single request.

Response Parameters

Updated User

Update Profile

POST /api/v1/users/${userId}

Updates a user's profile or credentials with partial update semantics

Important: Use the POST method for partial updates. Unspecified properties are set to null with PUT.

Request Parameters

Parameter	Description	Param Type	DataType	Required
userId	ID of user to update	URL	String	TRUE
strict	If true, validates against minimum age and history password policy	Query	String	FALSE
profile	Updated profile for user	Body	Profile Object	FALSE
credentials	Update credentials for user	Body	Credentials Object	FALSE

profile and credentials can be updated independently or with a single request.

Response Parameters

Updated User

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@update.example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  }
}' "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2015-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@update.example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

Set Password

Sets passwords without validating existing user credentials

This is an administrative operation. For operations that validate credentials refer to Reset Password, Forgot Password, and Change Password.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "credentials": {
    "password" : { "value": "uTVM,TPw55" }
  }
}' "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

Set Recovery Question & Answer

Sets recovery question and answer without validating existing user credentials

This is an administrative operation. For an operation that requires validation, see Change Recovery Question.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "credentials": {
    "recovery_question": {
      "question": "How many roads must a man walk down?",
      "answer": "forty two"
    }
  }
}' "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-07-02T21:36:25.344Z",
  "passwordChanged": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "I have a new recovery question?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

Get Assigned App Links

GET /api/v1/users/${userId}/appLinks

CORS

Fetches appLinks for all direct or indirect (via group membership) assigned applications

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE

Response Parameters

Array of App Links

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/appLinks"

Response Example

[
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "label": "Google Apps Mail",
    "linkUrl": "https://{yourOktaDomain}/home/google/0oa3omz2i9XRNSRIHBZO/50",
    "logoUrl": "https://{yourOktaDomain}/img/logos/google-mail.png",
    "appName": "google",
    "appInstanceId": "0oa3omz2i9XRNSRIHBZO",
    "appAssignmentId": "0ua3omz7weMMMQJERBKY",
    "credentialsSetup": false,
    "hidden": false,
    "sortOrder": 0
  },
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "label": "Google Apps Calendar",
    "linkUrl": "https://{yourOktaDomain}/home/google/0oa3omz2i9XRNSRIHBZO/54",
    "logoUrl": "https://{yourOktaDomain}/img/logos/google-calendar.png",
    "appName": "google",
    "appInstanceId": "0oa3omz2i9XRNSRIHBZO",
    "appAssignmentId": "0ua3omz7weMMMQJERBKY",
    "credentialsSetup": false,
    "hidden": false,
    "sortOrder": 1
  },
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "label": "Box",
    "linkUrl": "https://{yourOktaDomain}/home/boxnet/0oa3ompioiQCSTOYXVBK/72",
    "logoUrl": "https://{yourOktaDomain}/img/logos/box.png",
    "appName": "boxnet",
    "appInstanceId": "0oa3ompioiQCSTOYXVBK",
    "appAssignmentId": "0ua3omx46lYEZLPPRWBO",
    "credentialsSetup": false,
    "hidden": false,
    "sortOrder": 3
  },
  {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "label": "Salesforce.com",
    "linkUrl": "https://{yourOktaDomain}/home/salesforce/0oa12ecnxtBQMKOXJSMF/46",
    "logoUrl": "https://{yourOktaDomain}/img/logos/salesforce_logo.png",
    "appName": "salesforce",
    "appInstanceId": "0oa12ecnxtBQMKOXJSMF",
    "appAssignmentId": "0ua173qgj5VAVOBQMCVB",
    "credentialsSetup": true,
    "hidden": false,
    "sortOrder": 2
  }
]

Get User's Groups

GET /api/v1/users/${userId}/groups

CORS

Fetches the groups of which the user is a member

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE

Response Parameters

Array of Groups

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/groups"

Response Example

[
  {
    "id": "0gabcd1234",
    "profile": {
      "name": "Cloud App Users",
      "description": "Users can access cloud apps"
    }
  },
  {
    "id": "0gefgh5678",
    "profile": {
      "name": "Internal App Users",
      "description": "Users can access internal apps"
    }
  }
]

Lifecycle Operations

Lifecycle operations are non-idempotent operations that initiate a state transition for a user's status. Some operations are asynchronous while others are synchronous. The user's current status limits what operations are allowed. For example, you can't unlock a user that is ACTIVE.

Activate User

POST /api/v1/users/${userId}/lifecycle/activate

Activates a user

This operation can only be performed on users with a STAGED status. Activation of a user is an asynchronous operation.

The user's transitioningToStatus property has a value of ACTIVE during activation to indicate that the user hasn't completed the asynchronous operation.
The user's status is ACTIVE when the activation process is complete.

Users who don't have a password must complete the welcome flow by visiting the activation link to complete the transition to ACTIVE status.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
id	`id` of user	URL	String	TRUE
sendEmail	Sends an activation email to the user if `true`	Query	Boolean	FALSE	TRUE

Response Parameters

Returns empty object by default.
If sendEmail is false, returns an activation link for the user to set up their account. The activation token can be used to create a custom activation link.

{
  "activationUrl": "https://{yourOktaDomain}/welcome/XE6wE17zmphl3KqAPFxO",
  "activationToken": "XE6wE17zmphl3KqAPFxO"
}

If a password was set before the user was activated, then user must login with with their password or the activationToken and not the activation link. More information about using the activationToken to login can be found in the Authentication API.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate?sendEmail=false"

Response Example

{
  "activationUrl": "https://{yourOktaDomain}/welcome/XE6wE17zmphl3KqAPFxO",
  "activationToken": "XE6wE17zmphl3KqAPFxO"
}

Reactivate User

POST /api/v1/users/${userId}/lifecycle/reactivate

Reactivates a user

This operation can only be performed on users with a PROVISIONED status. This operation restarts the activation workflow if for some reason the user activation was not completed when using the activationToken from Activate User.

Users that don't have a password must complete the flow by completing Reset Password and MFA enrollment steps to transition the user to ACTIVE status.

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE
sendEmail	Sends an activation email to the user if `true`. Default value is `false`.	Query	Boolean	FALSE

Response Parameters

Returns empty object by default.
If sendEmail is false, returns an activation link for the user to set up their account. The activation token can be used to create a custom activation link.

{
  "activationUrl": "https://{yourOktaDomain}/welcome/XE6wE17zmphl3KqAPFxO",
  "activationToken": "XE6wE17zmphl3KqAPFxO"
}

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reactivate?sendEmail=false"

Response Example (Success)

{
  "activationUrl": "https://{yourOktaDomain}/welcome/XE6wE17zmphl3KqAPFxO",
  "activationToken": "XE6wE17zmphl3KqAPFxO"
}

Response Example (Unexpected user status)

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000038",
  "errorSummary": "This operation is not allowed in the user's current status.",
  "errorLink": "E0000038",
  "errorId": "oaefEpMS5yqTMGYEfxp0S_knw",
  "errorCauses": []
}

Deactivate User

POST /api/v1/users/${userId}/lifecycle/deactivate

Deactivates a user

This operation can only be performed on users that do not have a DEPROVISIONED status. Deactivation of a user is an asynchronous operation.

The user's transitioningToStatus property is DEPROVISIONED during deactivation to indicate that the user hasn't completed the asynchronous operation.
The user's status is DEPROVISIONED when the deactivation process is complete.

Important: Deactivating a user is a destructive operation. The user is deprovisioned from all assigned applications which may destroy their data such as email or files. This action cannot be recovered!

Request Parameters

Parameter	Description	Param Type	DataType	Required
userId	ID of user	URL	String	TRUE
sendEmail	Sends a deactivation email to the administrator if `true`. Default value is `false`.	Query	Boolean	FALSE

Response Parameters

Returns an empty object.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate?sendEmail=true"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

Suspend User

POST /api/v1/users/${userId}/lifecycle/suspend

Suspends a user

This operation can only be performed on users with an ACTIVE status. The user has a status of SUSPENDED when the process is complete.

Suspended users:

Can't log in to Okta. Their group and app assignments are retained.
Can only be unsuspended or deactivated.

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE

Response Parameters

Returns an empty object

Passing an invalid id returns a 404 Not Found status code with error code E0000007.
Passing an id that is not in the ACTIVE state returns a 400 Bad Request status code with error code E0000001.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/suspend"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

Unsuspend User

POST /api/v1/users/${userId}/lifecycle/unsuspend

Unsuspends a user and returns them to the ACTIVE state

This operation can only be performed on users that have a SUSPENDED status.

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE

Response Parameters

Returns an empty object.

Passing an invalid id returns a 404 Not Found status code with error code E0000007. Passing an id that is not in the SUSPENDED state returns a 400 Bad Request status code with error code E0000001.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/unsuspend"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

Deleting users is an Early Access feature.

Delete User

DELETE /api/v1/users/${userId}

Deletes a user permanently. This operation can only be performed on users that have a DEPROVISIONED status. This action cannot be recovered!

This operation on a user that hasn't been deactivated causes that user to be deactivated. A second delete operation is required to delete the user.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
id	`id` of user	URL	String	TRUE
sendEmail	Sends a deactivation email to the administrator if `true`. Default value is `false`.	Query	Boolean	FALSE	FALSE

Response Parameters

Returns an empty object.

Passing an invalid id returns a 404 Not Found status code with error code E0000007.

Request Example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR?sendEmail=true"

Response Example

HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{}

Unlock User

POST /api/v1/users/${userId}/lifecycle/unlock

Unlocks a user with a LOCKED_OUT status and returns them to ACTIVE status. Users will be able to login with their current password.

Note: This operation works with Okta-mastered users. It doesn't support directory-mastered accounts such as Active Directory.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
id	`id` of user	URL	String	TRUE

Response Parameters

Returns an empty object

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/unlock"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

Reset Password

POST /api/v1/users/${userId}/lifecycle/reset_password

Generates a one-time token (OTT) that can be used to reset a user's password. The OTT link can be automatically emailed to the user or returned to the API caller and distributed using a custom flow.

This operation will transition the user to the status of RECOVERY and the user will not be able to login or initiate a forgot password flow until they complete the reset flow.

Note: You can also use this API to convert a user with the Okta Credential Provider to a use a Federated Provider. After this conversion, the user cannot directly sign in with password. The second example demonstrates this usage.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
id	`id` of user	URL	String	TRUE
sendEmail	Sends reset password email to the user if `true`	Query	Boolean	FALSE	TRUE

To ensure a successful password recovery lookup if an email address is associated with multiple users:

Okta no longer includes deactivated users in the lookup.
The lookup searches login IDs first, then primary email addresses, and then secondary email addresses.

Response Parameters

Returns an empty object by default.
IfsendEmail is false, returns a link for the user to reset their password.

{
  "resetPasswordUrl": "https://{yourOktaDomain}/reset_password/XE6wE17zmphl3KqAPFxO"
}

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password?sendEmail=false"

Response Example

{
  "resetPasswordUrl": "https://{yourOktaDomain}/reset_password/XE6wE17zmphl3KqAPFxO"
}

Request Example (Convert a User to a Federated User)

To convert a user to a federated user, pass FEDERATION as the provider in the Provider Object. The sendEmail parameter must be false or omitted for this type of conversion.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password?provider=FEDERATION&sendEmail=false"

Response Example

{}

Expire Password

POST /api/v1/users/${userId}/lifecycle/expire_password

This operation transitions the user status to PASSWORD_EXPIRED so that the user is required to change their password at their next login. If tempPassword is included in the request, the user's password is reset to a temporary password that is returned, and then the temporary password is expired.

If you have integrated Okta with your on-premise Active Directory (AD), then setting a user's password as expired in Okta also expires the password in Active Directory. When the user tries to log in to Okta, delegated authentication finds the password-expired status in the Active Directory, and the user is presented with the password-expired page where he or she can change the password.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
id	`id` of user	URL	String	TRUE
tempPassword	Sets the user's password to a temporary password, if `true`	Query	Boolean	FALSE	FALSE

Response Parameters

Returns the complete user object by default
If tempPassword is true, returns the temporary password

{
    "tempPassword": "HR076gb6"
}

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password?tempPassword=false"

Response Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-06-27T16:35:28.000Z",
  "passwordChanged": "2013-06-24T16:39:19.000Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

Reset Factors

POST /api/v1/users/${userId}/lifecycle/reset_factors

This operation resets all factors for the specified user. All MFA factor enrollments returned to the unenrolled state. The user's status remains ACTIVE. This link is present only if the user is currently enrolled in one or more MFA factors.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
id	`id` of user	URL	String	TRUE

Response Parameters

Returns an empty object by default.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

User Sessions

Clear User Sessions

DELETE /api/v1/users/${userId}/sessions

Removes all active identity provider sessions. This forces the user to authenticate on the next operation. Optionally revokes OpenID Connect and OAuth refresh and access tokens issued to the user.

Note: This operation doesn't clear the sessions created for web sign in or native applications.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
userId	`id` of a user	URL	String	TRUE
oauthTokens	Revoke issued OpenID Connect and OAuth refresh and access tokens	Query	Boolean	FALSE	FALSE

Response Parameters

204 No Content

Request Example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/sessions"

Response Example

`204 No Content`

Credential Operations

Forgot Password

POST /api/v1/users/${userId}/credentials/forgot_password

Generates a one-time token (OTT) that can be used to reset a user's password

The user will be required to validate their security question's answer when visiting the reset link. This operation can only be performed on users with an ACTIVE status and a valid recovery question credential.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
id	`id` of user	URL	String	TRUE
sendEmail	Sends a forgot password email to the user if `true`	Query	Boolean	FALSE	TRUE

To ensure a successful password recovery lookup if an email address is associated with multiple users:

Okta no longer includes deactivated users in the lookup.
The lookup searches login IDs first, then primary email addresses, and then secondary email addresses.

Response Parameters

Returns an empty object by default
If sendEmail is false, returns a link for the user to reset their password.

{
  "resetPasswordUrl": "https://{yourOktaDomain}/reset_password/XE6wE17zmphl3KqAPFxO"
}

This operation does not affect the status of the user.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password?sendEmail=false"

Response Example

{
  "resetPasswordUrl": "https://{yourOktaDomain}/reset_password/XE6wE17zmphl3KqAPFxO"
}

POST /api/v1/users/${userId}/credentials/forgot_password

Sets a new password for a user by validating the user's answer to their current recovery question

This operation can only be performed on users with an ACTIVE status and a valid recovery question credential.

Important: This operation is intended for applications that need to implement their own forgot password flow. You are responsible for mitigation of all security risks such as phishing and replay attacks. The best practice is to generate a short-lived, one-time token (OTT) that is sent to a verified email account.

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE
password	New password for user	Body	Password Object	TRUE
recovery_question	Answer to user's current recovery question	Body	Recovery Question Object	TRUE

Response Parameters

Credentials of the user

This operation does not affect the status of the user.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "password": { "value": "uTVM,TPw55" },
  "recovery_question": { "answer": "Annie Oakley" }
}' "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"

Response Example

{
  "password": {},
  "recovery_question": {
    "question": "Who's a major player in the cowboy scene?"
  },
  "provider": {
    "type": "OKTA",
    "name": "OKTA"
  }
}

Change Password

POST /api/v1/users/${userId}/credentials/change_password

Changes a user's password by validating the user's current password

This operation can only be performed on users in STAGED, ACTIVE, PASSWORD_EXPIRED, or RECOVERY status that have a valid password credential

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE
strict	If true, validates against password minimum age policy	Query	String	FALSE
oldPassword	Current password for user	Body	Password Object	TRUE
newPassword	New password for user	Body	Password Object	TRUE

Response Parameters

Credentials of the user

The user transitions to ACTIVE status when successfully invoked in RECOVERY status.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "oldPassword": { "value": "tlpWENT2m" },
  "newPassword": { "value": "uTVM,TPw55" }
}' "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"

Response Example

{
  "password": {},
  "recovery_question": {
    "question": "Who's a major player in the cowboy scene?"
  },
  "provider": {
    "type": "OKTA",
    "name": "OKTA"
  }
}

Change Recovery Question

POST /api/v1/users/${userId}/credentials/change_recovery_question

Changes a user's recovery question & answer credential by validating the user's current password

This operation can only be performed on users in STAGED, ACTIVE or RECOVERY status that have a valid password credential

Request Parameters

Parameter	Description	Param Type	DataType	Required
id	`id` of user	URL	String	TRUE
password	Current password for user	Body	Password Object	TRUE
recovery_question	New recovery question & answer for user	Body	Recovery Question Object	TRUE

Response Parameters

Credentials of the user

This operation does not affect the status of the user.

Request Example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "password": { "value": "tlpWENT2m" },
  "recovery_question": {
    "question": "How many roads must a man walk down?",
    "answer": "forty two"
  }
}' "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"

Response Example

{
  "password": {},
  "recovery_question": {
    "question": "How many roads must a man walk down?"
  },
  "provider": {
    "type": "OKTA",
    "name": "OKTA"
  }
}

Early Access

A consent represents a user's explicit permission to allow an application to access resources protected by scopes. Consent grants are different from tokens because a consent can outlast a token, and there can be multiple tokens with varying sets of scopes derived from a single consent. When an application comes back and needs to get a new access token, it may not need to prompt the user for consent if they have already consented to the specified scopes. Consent grants remain valid until the user manually revokes them, or until the user, application, authorization server or scope is deactivated or deleted.

Hint: For all grant operations, you can use me instead of the userId in an endpoint that contains /users, in an active session with no SSWS token (API token). For example: https://{yourOktaDomain}/api/v1/users/me/grants returns all the grants for the active session user.

List Grants

Early Access

GET /api/v1/users/${userId}/grants

Lists all grants for the specified user

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
userId	ID of the user for whom you are fetching grants	URL	String	TRUE
expand	Valid value: `scope`. If specified, scope details are included in the `_embedded` attribute.	Query	String	FALSE
scopeId	The scope ID to filter on	Query	String	FALSE
limit	The number of grants to return (maximum 200)	Query	Number	FALSE	20
after	Specifies the pagination cursor for the next page of grants	Query	String	FALSE

Note: after should be treated as a cursor (an opaque value) and obtained through the next link relation.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/grants"

Response Example

[
    {
        "id": "oag3ih1zrm1cBFOiq0h6",
        "status": "ACTIVE",
        "created": "2017-10-30T22:06:53.000Z",
        "lastUpdated": "2017-10-30T22:06:53.000Z",
        "issuer": "https://{yourOktaDomain}/oauth2/ausain6z9zIedDCxB0h7",
        "clientId": "0oabskvc6442nkvQO0h7",
        "userId": "00u5t60iloOHN9pBi0h7",
        "scopeId": "scpCmCCV1DpxVkCaye2X",
        "_links": {
            "app": {
                "href": "https://{yourOktaDomain}/api/v1/apps/0oabskvc6442nkvQO0h7",
                "title": "My App"
            },
            "scope": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7/scopes/scpCmCCV1DpxVkCaye2X",
                "title": "My phone"
            },
            "client": {
                "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oabskvc6442nkvQO0h7",
                "title": "My App"
            },
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/grants/oag3ih1zrm1cBFOiq0h6",
                "hints": {
                    "allow": [
                        "GET",
                        "DELETE"
                    ]
                }
            },
            "user": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7",
                "title": "SAML Jackson"
            },
            "authorizationServer": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7",
                "title": "Example Authorization Server"
            }
        }
    }
]

Get a Grant

Early Access

GET /api/v1/users/${userId}/grants/${grantId}

Gets a grant for the specified user

Request Parameters

Parameter	Description	Param Type	DataType	Required
userId	ID of the user to whom the grant belongs	URL	String	TRUE
grantId	ID of the grant being fetched	Query	String	TRUE
expand	Valid value: `scope`. If specified, scope details are included in the `_embedded` attribute.	Query	String	FALSE

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/grants/oag3ih1zrm1cBFOiq0h6"

Response Example

{
    "id": "oag3ih1zrm1cBFOiq0h6",
    "status": "ACTIVE",
    "created": "2017-10-30T22:06:53.000Z",
    "lastUpdated": "2017-10-30T22:06:53.000Z",
    "issuer": "https://{yourOktaDomain}/oauth2/ausain6z9zIedDCxB0h7",
    "clientId": "0oabskvc6442nkvQO0h7",
    "userId": "00u5t60iloOHN9pBi0h7",
    "scopeId": "scpCmCCV1DpxVkCaye2X",
    "_links": {
        "app": {
            "href": "https://{yourOktaDomain}/api/v1/apps/0oabskvc6442nkvQO0h7",
            "title": "My App"
        },
        "scope": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7/scopes/scpCmCCV1DpxVkCaye2X",
            "title": "My phone"
        },
        "client": {
            "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oabskvc6442nkvQO0h7",
            "title": "My App"
        },
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/grants/oag3ih1zrm1cBFOiq0h6",
            "hints": {
                "allow": [
                    "GET",
                    "DELETE"
                ]
            }
        },
        "user": {
            "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7",
            "title": "SAML Jackson"
        },
        "authorizationServer": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7",
            "title": "Example Authorization Server"
        }
    }
}

List Grants for a User-Client Combination

Early Access

GET /api/v1/users/${userId}/clients/${clientId}/grants

Lists all grants for a specified user and client

Request Parameters

Parameter	Description	Parameter Type	DataType	Required	Default
userId	ID of the user whose grants you are listing for the specified `clientId`	URL	String	TRUE
clientId	ID of the client whose grants you are listing for the specified `userId`	URL	String	TRUE
expand	Valid value: `scope`. If specified, scope details are included in the `_embedded` attribute.	Query	String	FALSE
limit	The number of tokens to return (maximum 200)	Query	Number	FALSE	20
after	Specifies the pagination cursor for the next page of tokens	Query	String	FALSE

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/clients/0oabskvc6442nkvQO0h7/grants"

Response Example

[
    {
        "id": "oag3j3j33ILN7OFqP0h6",
        "status": "ACTIVE",
        "created": "2017-11-03T03:34:17.000Z",
        "lastUpdated": "2017-11-03T03:34:17.000Z",
        "issuer": "https://{yourOktaDomain}/oauth2/ausain6z9zIedDCxB0h7",
        "clientId": "0oabskvc6442nkvQO0h7",
        "userId": "00u5t60iloOHN9pBi0h7",
        "scopeId": "scpCmCCV1DpxVkCaye2X",
        "_links": {
            "app": {
                "href": "https://{yourOktaDomain}/api/v1/apps/0oabskvc6442nkvQO0h7",
                "title": "Test App for Groups Claim"
            },
            "scope": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7/scopes/scpCmCCV1DpxVkCaye2X",
                "title": "Your phone"
            },
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/grants/oag3j3j33ILN7OFqP0h6",
                "hints": {
                    "allow": [
                        "GET",
                        "DELETE"
                    ]
                }
            },
            "client": {
                "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oabskvc6442nkvQO0h7",
                "title": "Test App for Groups Claim"
            },
            "user": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7",
                "title": "Saml Jackson"
            },
            "authorizationServer": {
                "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7",
                "title": "Example Authorization Server"
            }
        }
    }
]

Revoke All Grants for a User

Early Access

DELETE /api/v1/users/${userId}/grants

Revokes all grants for a specified user

Request Paramters

Parameter	Description	Parameter Type	DataType	Required
userId	ID of the user whose grant is being revoked	URL	String	TRUE

Request Example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/grants"

Response Example

HTTP/1.1 204 No Content

Revoke a Grant for a User

Early Access

DELETE /api/v1/users/${userId}/grants/${grantId}

Revokes one grant for a specified user

Request Paramters

Parameter	Description	Parameter Type	DataType	Required
userId	ID of the user whose grant is being revoked	URL	String	TRUE
grantId	ID of the grant being revoked	URL	String	TRUE

Request Example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/grants/oag3ih1zrm1cBFOiq0h6"

Response Example

HTTP/1.1 204 No Content

Revoke Grants for User and Client

Early Access

DELETE /api/v1/users/${userId}/clients/${clientId}/grants

Revokes all grants for the specified user and client

Request Parameters

Parameter	Description	Parameter Type	DataType	Required
userId	ID of the user whose grants are being revoked for the specified client	URL	String	TRUE
clientId	ID of the client who was granted consent by the specified user	URL	String	TRUE

Request Example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/clients/0oabskvc6442nkvQO0h7/grants"

Response Example

HTTP/1.1 204 No Content

User OAuth 2.0 Token Management Operations

List Refresh Tokens
Get Refresh Token
Revoke All Refresh Tokens
Revoke Refresh Token

These endpoints allow you to manage tokens issued by an Authorization Server for a particular User and Client. For example, you could revoke every active refresh token for a User in the context of a specific Client. You can also revoke specific tokens or manage tokens at the Authorization Server level.

Read Validate Access Tokens to understand more about how OAuth 2.0 tokens work.

Early Access

List Refresh Tokens

Early Access

GET /api/v1/users/${userId}/clients/${clientId}/tokens

Lists all refresh tokens issued for the specified User and Client.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
userId	ID of the user for whom you are fetching tokens	URL	String	TRUE
clientId	ID of the client	URL	String	TRUE
expand	Valid value: `scope`. If specified, scope details are included in the `_embedded` attribute.	Query	String	FALSE
limit	The number of tokens to return (maximum 200)	Query	Number	FALSE	20
after	Specifies the pagination cursor for the next page of tokens	Query	String	FALSE

Note: after should be treated as a cursor (an opaque value) and obtained through the next link relation.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/tokens"

Response Example

[
  {
    "id": "oar579Mcp7OUsNTlo0g3",
    "status": "ACTIVE",
    "created": "2018-03-09T03:18:06.000Z",
    "lastUpdated": "2018-03-09T03:18:06.000Z",
    "expiresAt": "2018-03-16T03:18:06.000Z",
    "issuer": "https://{yourOktaDomain}/oauth2/ausain6z9zIedDCxB0h7",
    "clientId": "0oabskvc6442nkvQO0h7",
    "userId": "00u5t60iloOHN9pBi0h7",
    "scopes": [
      "offline_access",
      "car:drive"
    ],
    "_links": {
      "app": {
        "href": "https://{yourOktaDomain}/api/v1/apps/0oabskvc6442nkvQO0h7",
        "title": "Native"
      },
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/tokens/oar579Mcp7OUsNTlo0g3"
      },
      "revoke": {
        "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/tokens/oar579Mcp7OUsNTlo0g3",
        "hints": {
          "allow": [
            "DELETE"
          ]
        }
      },
      "client": {
        "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oabskvc6442nkvQO0h7",
        "title": "Example Client App"
      },
      "user": {
        "href": "https://{yourOktaDomain}/api/v1/users/00upcgi9dyWEOeCwM0g3",
        "title": "Saml Jackson"
      },
      "authorizationServer": {
        "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7",
        "title": "Example Authorization Server"
      }
    }
  }
]

Get Refresh Token

Early Access

GET /api/v1/users/${userId}/clients/${clientId}/tokens/${tokenId}

Gets a refresh token issued for the specified User and Client.

Request Parameters

Parameter	Description	Param Type	DataType	Required	Default
userId	ID of the user for whom you are fetching tokens	URL	String	TRUE
clientId	ID of the client	URL	String	TRUE
tokenId	ID of the token	URL	String	TRUE
expand	Valid value: `scope`. If specified, scope details are included in the `_embedded` attribute.	Query	String	FALSE
limit	The number of grants to return (maximum 200)	Query	Number	FALSE	20
after	Specifies the pagination cursor for the next page of grants	Query	String	FALSE

Note: after should be treated as a cursor (an opaque value) and obtained through the next link relation.

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/tokens/oar579Mcp7OUsNTlo0g3?expand=scope"

Response Example

{
  "id": "oar579Mcp7OUsNTlo0g3",
  "status": "ACTIVE",
  "created": "2018-03-09T03:18:06.000Z",
  "lastUpdated": "2018-03-09T03:18:06.000Z",
  "expiresAt": "2018-03-16T03:18:06.000Z",
  "issuer": "https://{yourOktaDomain}/oauth2/ausain6z9zIedDCxB0h7",
  "clientId": "0oabskvc6442nkvQO0h7",
  "userId": "00u5t60iloOHN9pBi0h7",
  "scopes": [
    "offline_access",
    "car:drive"
  ],
  "_embedded": {
    "scopes": [
      {
        "id": "scppb56cIl4GvGxy70g3",
        "name": "offline_access",
        "description": "Requests a refresh token by default, used to obtain more access tokens without re-prompting the user for authentication.",
        "_links": {
          "scope": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7/scopes/scppb56cIl4GvGxy70g3",
            "title": "offline_access"
          }
        }
      },
      {
        "id": "scp142iq2J8IGRUCS0g4",
        "name": "car:drive",
        "displayName": "Drive car",
        "description": "Allows the user to drive a car.",
        "_links": {
          "scope": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7/scopes/scp142iq2J8IGRUCS0g4",
            "title": "Drive car"
          }
        }
      }
    ]
  },
  "_links": {
    "app": {
      "href": "https://{yourOktaDomain}/api/v1/apps/0oabskvc6442nkvQO0h7",
      "title": "Native"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/tokens/oar579Mcp7OUsNTlo0g3"
    },
    "revoke": {
      "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/tokens/oar579Mcp7OUsNTlo0g3",
      "hints": {
        "allow": [
          "DELETE"
        ]
      }
    },
    "client": {
      "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oabskvc6442nkvQO0h7",
      "title": "Example Client App"
    },
    "user": {
      "href": "https://{yourOktaDomain}/api/v1/users/00upcgi9dyWEOeCwM0g3",
      "title": "Saml Jackson"
    },
    "authorizationServer": {
      "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7",
      "title": "Example Authorization Server"
    }
  }
}

Revoke All Refresh Tokens

Early Access

DELETE /api/v1/users/${userId}/clients/${clientId}/tokens

Revokes all refresh tokens issued for the specified User and Client. Any access tokens issued with these refresh tokens will also be revoked, but access tokens issued without a refresh token will not be affected.

Request Parameters

Parameter	Description	Parameter Type	DataType	Required
userId	ID of the user whose grants are being revoked for the specified client	URL	String	TRUE
clientId	ID of the client who was granted consent by the specified user	URL	String	TRUE

Request Example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/clients/0oabskvc6442nkvQO0h7/tokens"

Response Example

HTTP/1.1 204 No Content

Revoke Refresh Token

Early Access

DELETE /api/v1/users/${userId}/clients/${clientId}/tokens/${tokenId}

Revokes the specified refresh token. If an access token was issued with this refresh token, it will also be revoked.

Request Parameters

Parameter	Description	Parameter Type	DataType	Required
userId	ID of the user whose grants are being revoked for the specified client	URL	String	TRUE
clientId	ID of the client who was granted consent by the specified user	URL	String	TRUE
tokenId	ID of the token	URL	String	TRUE

Request Example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/clients/0oabskvc6442nkvQO0h7/tokens/oar579Mcp7OUsNTlo0g3"

Response Example

HTTP/1.1 204 No Content

User Client Resource Operations

Early Access

List Client Resources for a User

Early Access

GET /api/v1/users/${userId}/clients

Lists all client resources for which the specified user has grants or tokens.

Request Parameters

Parameter	Description	Parameter Type	DataType	Required
userId	ID of the user	URL	String	TRUE

Request Example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/clients"

Response Example

[
    {
        "client_id": "0oabskvc6442nkvQO0h7",
        "client_name": "My App",
        "client_uri": null,
        "logo_uri": null,
        "_links": {
            "grants": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/grants"
            },
            "tokens": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7/clients/0oabskvc6442nkvQO0h7/tokens"
            }
        }
    }
]

User Model

Example

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "ACTIVE",
  "created": "2013-06-24T16:39:18.000Z",
  "activated": "2013-06-24T16:39:19.000Z",
  "statusChanged": "2013-06-24T16:39:19.000Z",
  "lastLogin": "2013-06-24T17:39:19.000Z",
  "lastUpdated": "2013-06-27T16:35:28.000Z",
  "passwordChanged": "2013-06-24T16:39:19.000Z",
  "profile": {
    "login": "isaac.brock@example.com",
    "firstName": "Isaac",
    "lastName": "Brock",
    "nickName": "issac",
    "displayName": "Isaac Brock",
    "email": "isaac.brock@example.com",
    "secondEmail": "isaac@example.org",
    "profileUrl": "http://www.example.com/profile",
    "preferredLanguage": "en-US",
    "userType": "Employee",
    "organization": "Okta",
    "title": "Director",
    "division": "R&D",
    "department": "Engineering",
    "costCenter": "10",
    "employeeNumber": "187",
    "mobilePhone": "+1-555-415-1337",
    "primaryPhone": "+1-555-514-1337",
    "streetAddress": "301 Brannan St.",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94107",
    "countryCode": "US"
  },
  "credentials": {
    "password": {},
    "recovery_question": {
      "question": "Who's a major player in the cowboy scene?"
    },
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "resetPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
    },
    "resetFactors": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
    },
    "expirePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
    },
    "forgotPassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
    },
    "changeRecoveryQuestion": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
    },
    "changePassword": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
    }
  }
}

User Properties

The User model defines several read-only properties:

Property	Description	DataType	Nullable	Unique	Readonly
userId	unique key for user	String	FALSE	TRUE	TRUE
status	current status of user	`STAGED`, `PROVISIONED`, `ACTIVE`, `RECOVERY`, `LOCKED_OUT`, `PASSWORD_EXPIRED`, `SUSPENDED`, or `DEPROVISIONED`	FALSE	FALSE	TRUE
created	timestamp when user was created	Date	FALSE	FALSE	TRUE
activated	timestamp when transition to `ACTIVE` status completed	Date	FALSE	FALSE	TRUE
statusChanged	timestamp when status last changed	Date	TRUE	FALSE	TRUE
lastLogin	timestamp of last login	Date	TRUE	FALSE	TRUE
lastUpdated	timestamp when user was last updated	Date	FALSE	FALSE	TRUE
passwordChanged	timestamp when password last changed	Date	TRUE	FALSE	TRUE
transitioningToStatus	target status of an in-progress asynchronous status transition	`PROVISIONED`, `ACTIVE`, or `DEPROVISIONED`	TRUE	FALSE	TRUE
profile	user profile properties	Profile Object	FALSE	FALSE	FALSE
credentials	user's primary authentication and recovery credentials	Credentials Object	FALSE	FALSE	FALSE
_links	link relations for the user’s current `status`	JSON HAL	TRUE	FALSE	TRUE
_embedded	embedded resources related to the user	JSON HAL	TRUE	FALSE	TRUE

Metadata properties such as id, status, timestamps, _links, and _embedded are only available after a user is created.

The activated timestamp will only be available for users activated after 06/30/2013.
ThestatusChanged and lastLogin timestamps will be missing for users created before 06/30/2013 and updated on next status change or login.

User Status

The following diagram shows the state model for a user:

STAGED, PROVISIONED, ACTIVE, RECOVERY, LOCKED_OUT, PASSWORD_EXPIRED, or DEPROVISIONED

Understanding User Status Values

The status of a user changes in response to explicit events, such as admin-driven lifecycle changes, user login, or self-service password recovery. Okta doesn't asynchronously sweep through users and update their password expiry state, for example. Instead, Okta evaluates password policy at login time, notices the password has expired, and moves the user to the expired state. When running reports, remember that the data is valid as of the last login or lifecycle event for that user.

Profile Object

Specifies standard and custom profile properties for a user.

{
  "profile": {
    "login": "isaac.brock@example.com",
    "firstName": "Isaac",
    "lastName": "Brock",
    "nickName": "issac",
    "displayName": "Isaac Brock",
    "email": "isaac.brock@example.com",
    "secondEmail": "isaac@example.org",
    "profileUrl": "http://www.example.com/profile",
    "preferredLanguage": "en-US",
    "userType": "Employee",
    "organization": "Okta",
    "title": "Director",
    "division": "R&D",
    "department": "Engineering",
    "costCenter": "10",
    "employeeNumber": "187",
    "mobilePhone": "+1-555-415-1337",
    "primaryPhone": "+1-555-514-1337",
    "streetAddress": "301 Brannan St.",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94107",
    "countryCode": "US"
  }
}

Default Profile Properties

The default user profile is based on the System for Cross-Domain Identity Management: Core Schema and has following standard properties:

Property	Description	DataType	Nullable	Unique	Readonly	MinLength	MaxLength	Validation
login	unique identifier for the user (`username`)	String	FALSE	TRUE	FALSE	5	100	pattern
email	primary email address of user	String	FALSE	TRUE	FALSE	5	100	RFC 5322 Section 3.2.3
secondEmail	secondary email address of user typically used for account recovery	String	TRUE	TRUE	FALSE	5	100	RFC 5322 Section 3.2.3
firstName	given name of the user (`givenName`)	String	FALSE (default)	FALSE	FALSE	1	50
lastName	family name of the user (`familyName`)	String	FALSE (default)	FALSE	FALSE	1	50
middleName	middle name(s) of the user	String	TRUE	FALSE	FALSE
honorificPrefix	honorific prefix(es) of the user, or title in most Western languages	String	TRUE	FALSE	FALSE
honorificSuffix	honorific suffix(es) of the user	String	TRUE	FALSE	FALSE
title	user's title, such as "Vice President	String	TRUE	FALSE	FALSE
displayName	name of the user, suitable for display to end users	String	TRUE	FALSE	FALSE
nickName	casual way to address the user in real life	String	TRUE	FALSE	FALSE
profileUrl	url of user's online profile (e.g. a web page)	String	TRUE	FALSE	FALSE			URL
primaryPhone	primary phone number of user such as home number	String	TRUE	FALSE	FALSE	0	100
mobilePhone	mobile phone number of user	String	TRUE	FALSE	FALSE	0	100
streetAddress	full street address component of user's address	String	TRUE	FALSE	FALSE
city	city or locality component of user's address (`locality`)	String	TRUE	FALSE	FALSE
state	state or region component of user's address (`region`)	String	TRUE	FALSE	FALSE
zipCode	zipcode or postal code component of user's address (`postalCode`)	String	TRUE	FALSE	FALSE
countryCode	country name component of user's address (`country`)	String	TRUE	FALSE	FALSE			ISO 3166-1 alpha 2 "short" code format
postalAddress	mailing address component of user's address	String	TRUE	FALSE	FALSE
preferredLanguage	user's preferred written or spoken languages	String	TRUE	FALSE	FALSE			RFC 7231 Section 5.3.5
locale	user's default location for purposes of localizing items such as currency, date time format, numerical representations, etc.	String	TRUE	FALSE	FALSE			See Note for more details.
timezone	user's time zone	String	TRUE	FALSE	FALSE			IANA Time Zone database format
userType	used to identify the organization to user relationship such as "Employee" or "Contractor	String	TRUE	FALSE	FALSE
employeeNumber	organization or company assigned unique identifier for the user	String	TRUE	FALSE	FALSE
costCenter	name of a cost center assigned to user	String	TRUE	FALSE	FALSE
organization	name of user's organization	String	TRUE	FALSE	FALSE
division	name of user's division	String	TRUE	FALSE	FALSE
department	name of user's department	String	TRUE	FALSE	FALSE
managerId	`id` of a user's manager	String	TRUE	FALSE	FALSE
manager	displayName of the user's manager	String	TRUE	FALSE	FALSE

Note: A locale value is a concatenation of the ISO 639-1 two letter language code, an underscore, and the ISO 3166-1 2 letter country code. For example, en_US specifies the language English and country US.

Every user within your Okta organization must have a unique identifier for a login. This constraint applies to all users you import from other systems or applications such as Active Directory. Your organization is the top-level namespace to mix and match logins from all your connected applications or directories. Careful consideration of naming conventions for your login identifier will make it easier to onboard new applications in the future.

Okta has a default ambiguous name resolution policy for logins that include @-signs. (By default, logins must be formatted as email addresses and thus always include @-signs. That restriction can be removed using either the administrator UI or the Schemas API.) Users can login with their non-qualified short name (e.g. isaac.brock with login isaac.brock@example.com) as long as the short name is still unique within the organization.

Hint: Don't use a login with a / character. Although / is a valid character according to RFC 6531 section 3.3, a user with this character in their login can't be fetched by login due to security risks with escaping this character in URI paths. For more information about login, see Get User by ID.

Modifying Default Profile Properties

The only permitted customization of the default profile is to update permissions, to change whether the firstName and lastName properties are nullable, or to specify a pattern for login. You can use the Profile Editor in the administrator UI or the Schemas API to make schema modifications.

Custom Profile Properties

User profiles may be extended with custom properties but the property must first be added to the user profile schema before it can be referenced. You can use the Profile Editor in the administrator UI or the Schemas API to manage schema extensions.

Custom attributes may contain HTML tags. It is the client's responsibility to escape or encode this data before displaying it. Use best-practices to prevent cross-site scripting.

Credentials Object

Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the organization.

Property	DataType	Nullable	Unique	Readonly
password	Password Object	TRUE	FALSE	FALSE
recovery_question	Recovery Question Object	TRUE	FALSE	FALSE
provider	Provider Object	FALSE	FALSE	TRUE

{
  "password": {
    "value": "tlpWENT2m"
  },
  "recovery_question": {
    "question": "Who's a major player in the cowboy scene?",
    "answer": "Annie Oakley"
  },
  "provider": {
    "type": "OKTA",
    "name": "OKTA"
  }
}

Password Object

Specifies a password for a user

Property	DataType	Nullable	Unique	Readonly	MinLength	MaxLength	Validation
value	String	TRUE	FALSE	FALSE	Password Policy	72	Password Policy
hash	Hashed Password Object	TRUE	FALSE	FALSE	N/A	N/A

A password value is a write-only property. A password hash is a write-only property.

When a user has a valid password or imported hashed password, and a response object contains a password credential, then the Password Object is a bare object without the value property defined (e.g. password: {}) to indicate that a password value exists.

Default Password Policy

The password specified in the value property must meet the default password policy requirements:

Must be a minimum of 8 characters
Must have a character from the following groups:
- Upper case
- Lower case
- Digit
Must not contain the user's login or parts of the the login when split on the following characters: , . _ # @
- For example, a user with login isaac.brock@example.com will not be able set password brockR0cks! as the password contains the login part brock

Password policy requirements can be modified in the administrator UI (Security -> Policies)

Hashed Password Object

Specifies a hashed password that can be imported into Okta. This allows an existing password to be imported into Okta directly from some other store. A hashed password may be specified in a Password Object when creating or updating a user, but not for other operations. When updating a user with a hashed password the user must have the STAGED status.

Property	DataType	Description	Required	Min Value	Max Value
algorithm	String	The algorithm used to hash the password. Must be set to `BCRYPT`, `SHA-512`, `SHA-256`, `SHA-1` or `MD5`	TRUE	N/A	N/A
value	String	For `SHA-512`, `SHA-256`, `SHA-1`, `MD5`: This is the actual base64-encoded hashed password. For `BCRYPT`: This is the actual radix64-encoded hashed password.	TRUE	N/A	N/A
salt	String	For `SHA-512`, `SHA-256`, `SHA-1`, `MD5`: Specifies the base64-encoded password salt used to generate the hash. For `BCRYPT`: Specifies the radix64-encoded password salt used to generate the hash.	TRUE	22 (only for `BCRYPT` algorithm)	22 (only for `BCRYPT` algorithm)
workFactor	Integer	Governs the strength of the hash, and the time required to compute it. Only relevant for `BCRYPT` algorithm	Only for `BCRYPT` algorithm	1	20
saltOrder	String	Specifies whether salt was pre- or postfixed to the password before hashing. Only relevant for `SHA-512`, `SHA-256`, `SHA-1`, `MD5` algorithms. Must be set to `PREFIX` or `POSTFIX`	Only for `Salted SHA-512`, `Salted SHA-256`, `Salted SHA-1`, `Salted MD5` algorithms	N/A	N/A

BCRYPT Hashed Password Object Example

"password" : {
  "hash": {
    "algorithm": "BCRYPT",
    "workFactor": 10,
    "salt": "rwh3vH166HCH/NT9XV5FYu",
    "value": "qaMqvAPULkbiQzkTCWo5XDcvzpk8Tna"
  }
}

SHA-512 Hashed Password Object Example

"password" : {
  "hash": {
    "algorithm": "SHA-512",
    "salt": "TXlTYWx0",
    "saltOrder": "PREFIX",
    "value": "QrozP8a+KfoHu6mPFysxLoO5LMQsd2Fw6IclZUf8xQjetJOCGS93vm68h+VaFX0LHSiF/GxQkykq1vofmx6NGA=="
  }
}

SHA-256 Hashed Password Object Example

"password" : {
  "hash": {
    "algorithm": "SHA-256",
    "salt": "MPu13OmY",
    "saltOrder": "PREFIX",
    "value": "Gjxo7mxvvzQWa83ovhYRUH2dWUhC1N77Ntc56UfI4sY"
  }
}

SHA-1 Hashed Password Object Example

"password" : {
  "hash": {
    "algorithm": "SHA-1",
    "salt": "UEO3wsAsgzQ=",
    "saltOrder": "POSTFIX",
    "value": "xjrauE6J6kbjcvMjWSSc+PsBBls="
  }
}

MD5 Hashed Password Object Example

"password" : {
  "hash": {
    "algorithm": "MD5",
    "salt": "TXlTYWx0",
    "saltOrder": "PREFIX",
    "value": "jqACjUUFXM1XE6NiLALAbA=="
  }
}

Hashing Function

Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, and MD5 hashing functions for password import.

Default Password Policy

Because the plain text password is not specified when a hashed password is provided, password policy is not applied.

Recovery Question Object

Specifies a secret question and answer that is validated (case insensitive) when a user forgets their password or unlocks their account. The answer property is write-only.

Property	DataType	Nullable	Unique	Readonly	MinLength	MaxLength
question	String	TRUE	FALSE	FALSE	1	100
answer	String	TRUE	FALSE	FALSE	1	100

Provider Object

Specifies the authentication provider that validates the user's password credential. The user's current provider is managed by the Delegated Authentication settings for your organization. The provider object is read-only.

Property	DataType	Nullable	Unique	Readonly
type	`OKTA`, `ACTIVE_DIRECTORY`,`LDAP`, `FEDERATION`, `SOCIAL` or `IMPORT`	FALSE	FALSE	TRUE
name	String	TRUE	FALSE	TRUE

ACTIVE_DIRECTORY or LDAP providers specify the directory instance name as the name property.

Users with a FEDERATION or SOCIAL authentication provider do not support a password or recovery_question credential and must authenticate via a trusted Identity Provider.

IMPORT specifies a hashed password that was imported from an external source.

Links Object

Specifies link relations (See Web Linking) available for the current status of a user. The Links object is used for dynamic discovery of related resources, lifecycle operations, and credential operations. The Links object is read-only.

Individual Users vs. Collection of Users

For an individual User result, the Links object contains a full set of link relations available for that User as determined by your policies. For a collection of Users, the Links object contains only the self link. Operations that return a collection of Users include List Users and List Group Members.

Here are some links that may be available on a User, as determined by your policies:

Link Relation Type	Description
self	A self-referential link to this user
activate	Lifecycle action to activate the user
deactivate	Lifecycle action to deactivate the user
suspend	Lifecycle action to suspend the user
unsuspend	Lifecycle action to unsuspend the user
resetPassword	Lifecycle action to trigger a password reset
expirePassword	Lifecycle action to expire the user's password
resetFactors	Lifecycle action to reset all MFA factors
unlock	Lifecycle action to unlock a locked-out user
forgotPassword	Resets a user's password by validating the user's recovery credential.
changePassword	Changes a user's password validating the user's current password
changeRecoveryQuestion	Changes a user's recovery credential by validating the user's current password

Early Access

{
    "id": "oag2n8HU1vTmvCdQ50g3",
    "status": "ACTIVE",
    "created": "2017-11-07T21:46:36.000Z",
    "lastUpdated": "2017-11-07T21:46:36.000Z",
    "issuer": "https://{yourOktaDomain}/oauth2/ausain6z9zIedDCxB0h7",
    "clientId": "customClientIdNative",
    "userId": "00uol9oQZaWN47WQZ0g3",
    "scopeId": "scpp4bmzfCV7dHf8y0g3",
    "_embedded": {
        "scope": {
            "name": "bus:drive",
            "displayName": "test",
            "description": "Drive bus"
        }
    },
    "_links": {
        "app": {
            "href": "https://{yourOktaDomain}:1802/api/v1/apps/0oaozwn7Qlfx0wl280g3",
            "title": "Native client"
        },
        "scope": {
            "href": "https://{yourOktaDomain}:1802/api/v1/authorizationServers/ausoxdmNlCV4Rw9Ec0g3/scopes/scpp4bmzfCV7dHf8y0g3",
            "title": "test"
        },
        "self": {
            "href": "https://{yourOktaDomain}:1802/api/v1/users/00uol9oQZaWN47WQZ0g3/grants/oag2n8HU1vTmvCdQ50g3",
            "hints": {
                "allow": [
                    "GET",
                    "DELETE"
                ]
            }
        },
        "client": {
            "href": "https://{yourOktaDomain}:1802/oauth2/v1/clients/customClientIdNative",
            "title": "Native client"
        },
        "user": {
            "href": "https://{yourOktaDomain}:1802/api/v1/users/00uol9oQZaWN47WQZ0g3",
            "title": "Saml Jackson"
        },
        "authorizationServer": {
            "href": "https://{yourOktaDomain}/api/v1/authorizationServers/ausain6z9zIedDCxB0h7",
            "title": "Example Authorization Server"
        }
    }
}

Early Access

Property	Description	Datatype
Id	ID of this grant	String
status	Status of the grant. Valid values: `ACTIVE`, `REVOKED` or `EXPIRED`	String
created	Timestamp when the grant was created	Date
lastUpdated	Timestamp when the grant was last updated	Date
issuer	The complete URL of the authorization server for this grant	String
clientId	ID of the client for this grant	String
userId	ID of the user who consented to this grant	String
scopeId	ID of the scope to which this grant applies	String
_links	Discoverable resources related to the grant	JSON HAL
_embedded	If `expand`=`scope` is included in the request, information about the scope specified by `scopeId` is included in the response.	JSON HAL

Client Grant Object

Early Access

{
  "client_id": "0oab57tu2q6C0rYwM0h7",
  "client_name": "AWS Cognito",
  "client_uri": null,
  "logo_uri": "https://example.com/image/logo.jpg",
  "_links": {
     "grants": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ucmukel4KHsPARU0h7/clients/0oab57tu2q6C0rYwM0h7/grants"
        "hints": {
            "allow": [
                "GET",
                "DELETE"
            ]
        }
     }
  }
}

Client Grant Properties

Property	Description	Datatype	Unique
client_id	The client ID of the OAuth 2.0 client	String	TRUE
client_name	The name of the OAuth 2.0 client	String	TRUE
client_uri	The URI of the OAuth 2.0 client	String	FALSE
logo_uri	The logo URI of the OAuth 2.0 client	String	FALSE
_links	Discoverable resources related to the grant	JSON HAL	FALSE

Users API

Getting Started

User Operations

Create User

Request Parameters

Response Parameters

Create User without Credentials

Request Example

Response Example

Create User with Recovery Question

Request Example

Response Example

Create User with Password

Request Example

Response Example

Create User with Imported Hashed Password

Request Example

Response Example

Create User with Password & Recovery Question

Request Example

Response Example

Create User with Authentication Provider

Request Example

Response Example

Create User in Group

Request Example

Response Example

Get User

Request Parameters

Response Parameters

Get Current User

Request Example

Response Example

Get User with ID

Request Example

Response Example

Get User with Login

Request Example

Response Example

Get User with Login Shortname

Request Example

Response Example

List Users

Request Parameters

Response Parameters

List All Users

Request Example

Response Example

Find Users

Request Example

Response Example

List Users with a Filter

Filter Examples

Request Example: Status

Response Example

Request Example: Timestamp

Response Example

List Users with Search

Search Examples

Request Example

Response Example

Searching Arrays

Request Example for Array

Response Example for Array

Update User

Request Parameters

Response Parameters

Update Profile

Request Parameters

Response Parameters

Request Example

Response Example

Set Password

Request Example

Response Example

Set Recovery Question & Answer

Request Example

Response Example

Related Resources

Get Assigned App Links