Users

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

List all Users
CORS
OAuth 2.0: okta.users.read

Lists all users that do not have a status of 'DEPROVISIONED' (by default), up to the maximum (200 for most orgs), with pagination. A subset of users can be returned that match a supported filter expression or search criteria.

Request
query Parameters
q
string

Finds a user that matches firstName, lastName, and email properties

after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination for more information.

limit
integer <int32>
Default: 200

Specifies the number of results returned. Defaults to 10 if q is provided.

filter
string

Filters users with a supported expression for a subset of properties

search
string

Searches for users with a supported filtering expression for most properties. Okta recommends using this parameter for search for best performance.

sortBy
string
sortOrder
string
Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/users
Request samples
Response samples
application/json
[
  • {
    • "id": "00u118oQYT4TBGuay0g4",
    • "status": "ACTIVE",
    • "created": "2022-04-04T15:56:05.000Z",
    • "activated": null,
    • "statusChanged": null,
    • "lastLogin": "2022-05-04T19:50:52.000Z",
    • "lastUpdated": "2022-05-05T18:15:44.000Z",
    • "passwordChanged": "2022-04-04T16:00:22.000Z",
    • "type": {
      },
    • "profile": {
      },
    • "credentials": {
      },
    }
]

Create a User
CORS
OAuth 2.0: okta.users.manage

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

Request
query Parameters
activate
boolean
Default: true

Executes activation lifecycle operation when creating the user

provider
boolean
Default: false

Indicates whether to create a user with a specified authentication provider

nextLogin
string (UserNextLogin)

With activate=true, set nextLogin to "changePassword" to have the password be EXPIRED, so user must change it the next time they log in.

Value: "changePassword"
Request Body schema: application/json
object (UserCredentials)
object (PasswordCredential)
object (PasswordCredentialHash)
object (PasswordCredentialHook)
value
string <password>
object (AuthenticationProvider)
name
string
type
string (AuthenticationProviderType)
Enum: "ACTIVE_DIRECTORY" "FEDERATION" "IMPORT" "LDAP" "OKTA" "SOCIAL"
object (RecoveryQuestionCredential)
answer
string
question
string
groupIds
Array of strings
required
object (UserProfile)
city
string or null <= 128 characters
costCenter
string
countryCode
string or null <= 2 characters
department
string
displayName
string
division
string
email
string <email> [ 5 .. 100 ] characters
employeeNumber
string
firstName
string or null [ 1 .. 50 ] characters
honorificPrefix
string
honorificSuffix
string
lastName
string or null [ 1 .. 50 ] characters
locale
string (Language)

The language specified as an IETF BCP 47 language tag.

login
string <= 100 characters
manager
string
managerId
string
middleName
string
mobilePhone
string or null <= 100 characters
nickName
string
organization
string
postalAddress
string or null <= 4096 characters
preferredLanguage
string
primaryPhone
string or null <= 100 characters
profileUrl
string
secondEmail
string or null <email> [ 5 .. 100 ] characters
state
string or null <= 128 characters
streetAddress
string or null <= 1024 characters
timezone
string
title
string
userType
string
zipCode
string or null <= 50 characters
property name*
additional property
any
object (UserType)
description
string
displayName
string
id
string
name
string
Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/users
Request samples
application/json
{
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "groupIds": [
    • "string"
    ],
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "type": {
    • "description": "string",
    • "displayName": "string",
    • "id": "string",
    • "name": "string"
    }
}
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": "string",
    • "default": true,
    • "description": "string",
    • "displayName": "string",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdatedBy": "string",
    • "name": "string",
    • "_links": {
      }
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "property1": { },
    • "property2": { }
    }
}

Create a Linked Object for two User
CORS
OAuth 2.0: okta.users.manage

Creates a linked object for two users

Request
path Parameters
associatedUserId
required
string
primaryRelationshipName
required
string
primaryUserId
required
string
Responses
204

Success

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/users/{associatedUserId}/linkedObjects/{primaryRelationshipName}/{primaryUserId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Retrieve a User
CORS
OAuth 2.0: okta.users.read

Retrieves a user from your Okta organization

Request
path Parameters
userId
required
string
query Parameters
expand
string

Specifies additional metadata to include in the response. Possible value: blocks

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}
Request samples
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": "string",
    • "default": true,
    • "description": "string",
    • "displayName": "string",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdatedBy": "string",
    • "name": "string",
    • "_links": {
      }
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "property1": { },
    • "property2": { }
    }
}

Update a User
CORS
OAuth 2.0: okta.users.manage

Updates a user partially determined by the request parameters

Request
path Parameters
userId
required
string
query Parameters
strict
boolean
Request Body schema: application/json
object (UserCredentials)
object (PasswordCredential)
object (PasswordCredentialHash)
object (PasswordCredentialHook)
value
string <password>
object (AuthenticationProvider)
name
string
type
string (AuthenticationProviderType)
Enum: "ACTIVE_DIRECTORY" "FEDERATION" "IMPORT" "LDAP" "OKTA" "SOCIAL"
object (RecoveryQuestionCredential)
answer
string
question
string
object (UserProfile)
city
string or null <= 128 characters
costCenter
string
countryCode
string or null <= 2 characters
department
string
displayName
string
division
string
email
string <email> [ 5 .. 100 ] characters
employeeNumber
string
firstName
string or null [ 1 .. 50 ] characters
honorificPrefix
string
honorificSuffix
string
lastName
string or null [ 1 .. 50 ] characters
locale
string (Language)

The language specified as an IETF BCP 47 language tag.

login
string <= 100 characters
manager
string
managerId
string
middleName
string
mobilePhone
string or null <= 100 characters
nickName
string
organization
string
postalAddress
string or null <= 4096 characters
preferredLanguage
string
primaryPhone
string or null <= 100 characters
profileUrl
string
secondEmail
string or null <email> [ 5 .. 100 ] characters
state
string or null <= 128 characters
streetAddress
string or null <= 1024 characters
timezone
string
title
string
userType
string
zipCode
string or null <= 50 characters
property name*
additional property
any
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}
Request samples
application/json
{
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    }
}
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": "string",
    • "default": true,
    • "description": "string",
    • "displayName": "string",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdatedBy": "string",
    • "name": "string",
    • "_links": {
      }
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "property1": { },
    • "property2": { }
    }
}

Replace a User
CORS
OAuth 2.0: okta.users.manage

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

Request
path Parameters
userId
required
string
query Parameters
strict
boolean
Request Body schema: application/json
object (UserCredentials)
object (PasswordCredential)
object (PasswordCredentialHash)
object (PasswordCredentialHook)
value
string <password>
object (AuthenticationProvider)
name
string
type
string (AuthenticationProviderType)
Enum: "ACTIVE_DIRECTORY" "FEDERATION" "IMPORT" "LDAP" "OKTA" "SOCIAL"
object (RecoveryQuestionCredential)
answer
string
question
string
object (UserProfile)
city
string or null <= 128 characters
costCenter
string
countryCode
string or null <= 2 characters
department
string
displayName
string
division
string
email
string <email> [ 5 .. 100 ] characters
employeeNumber
string
firstName
string or null [ 1 .. 50 ] characters
honorificPrefix
string
honorificSuffix
string
lastName
string or null [ 1 .. 50 ] characters
locale
string (Language)

The language specified as an IETF BCP 47 language tag.

login
string <= 100 characters
manager
string
managerId
string
middleName
string
mobilePhone
string or null <= 100 characters
nickName
string
organization
string
postalAddress
string or null <= 4096 characters
preferredLanguage
string
primaryPhone
string or null <= 100 characters
profileUrl
string
secondEmail
string or null <email> [ 5 .. 100 ] characters
state
string or null <= 128 characters
streetAddress
string or null <= 1024 characters
timezone
string
title
string
userType
string
zipCode
string or null <= 50 characters
property name*
additional property
any
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/users/{userId}
Request samples
application/json
{
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    }
}
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": "string",
    • "default": true,
    • "description": "string",
    • "displayName": "string",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdatedBy": "string",
    • "name": "string",
    • "_links": {
      }
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "property1": { },
    • "property2": { }
    }
}

Delete a User
CORS
OAuth 2.0: okta.users.manage

Deletes a user permanently. This operation can only be performed on users that have a DEPROVISIONED status. This action cannot be recovered!. Calling this on an ACTIVE user will transition the user to DEPROVISIONED.

Request
path Parameters
userId
required
string
query Parameters
sendEmail
boolean
Default: false
Responses
204

No Content

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}
Request samples
Response samples
application/json
{
  • "errorCauses": [
    • {
      }
    ],
  • "errorCode": "string",
  • "errorId": "string",
  • "errorLink": "string",
  • "errorSummary": "string"
}

List all Clients
CORS
OAuth 2.0: okta.users.read

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

Request
path Parameters
userId
required
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients
Request samples
Response samples
application/json
[
  • {
    • "client_id": "string",
    • "client_name": "string",
    • "client_uri": "string",
    • "logo_uri": "string",
    • "_links": {
      }
    }
]

List all Grants for a Client
CORS
OAuth 2.0: okta.users.read

Lists all grants for a specified user and client

Request
path Parameters
userId
required
string
clientId
required
string
query Parameters
expand
string
after
string
limit
integer <int32>
Default: 20
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients/{clientId}/grants
Request samples
Response samples
application/json
[
  • {
    • "clientId": "string",
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": {
      },
    • "id": "string",
    • "issuer": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "scopeId": "string",
    • "source": "ADMIN",
    • "status": "ACTIVE",
    • "userId": "string",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Revoke all Grants for a Client
CORS
OAuth 2.0: okta.users.manage

Revokes all grants for the specified user and client

Request
path Parameters
userId
required
string
clientId
required
string
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/clients/{clientId}/grants
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

List all Refresh Tokens for a Client
CORS
OAuth 2.0: okta.users.read

Lists all refresh tokens issued for the specified User and Client

Request
path Parameters
userId
required
string
clientId
required
string
query Parameters
expand
string
after
string
limit
integer <int32>
Default: 20
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients/{clientId}/tokens
Request samples
Response samples
application/json
[
  • {
    • "clientId": "string",
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": {
      },
    • "expiresAt": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "issuer": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "scopes": [
      ],
    • "status": "ACTIVE",
    • "userId": "string",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Revoke all Refresh Tokens for a Client
CORS
OAuth 2.0: okta.users.manage

Revokes all refresh tokens issued for the specified User and Client

Request
path Parameters
userId
required
string
clientId
required
string
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/clients/{clientId}/tokens
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Retrieve a Refresh Token for a Client
CORS
OAuth 2.0: okta.users.read

Retrieves a refresh token issued for the specified User and Client

Request
path Parameters
userId
required
string
clientId
required
string
tokenId
required
string
query Parameters
expand
string
limit
integer
Default: 20
after
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients/{clientId}/tokens/{tokenId}
Request samples
Response samples
application/json
{
  • "clientId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "createdBy": {
    • "id": "string",
    • "type": "string"
    },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "issuer": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "scopes": [
    • "string"
    ],
  • "status": "ACTIVE",
  • "userId": "string",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "property1": { },
    • "property2": { }
    }
}

Revoke a Token for a Client
CORS
OAuth 2.0: okta.users.manage

Revokes the specified refresh token

Request
path Parameters
userId
required
string
clientId
required
string
tokenId
required
string
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/clients/{clientId}/tokens/{tokenId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Change Password
CORS
OAuth 2.0: okta.users.manage

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
path Parameters
userId
required
string
query Parameters
strict
boolean
Request Body schema: application/json
object (PasswordCredential)
object (PasswordCredentialHash)
algorithm
string (PasswordCredentialHashAlgorithm)
Enum: "BCRYPT" "MD5" "SHA-1" "SHA-256" "SHA-512"
salt
string
saltOrder
string
value
string
workFactor
integer
object (PasswordCredentialHook)
type
string
value
string <password>
object (PasswordCredential)
object (PasswordCredentialHash)
algorithm
string (PasswordCredentialHashAlgorithm)
Enum: "BCRYPT" "MD5" "SHA-1" "SHA-256" "SHA-512"
salt
string
saltOrder
string
value
string
workFactor
integer
object (PasswordCredentialHook)
type
string
value
string <password>
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/change_password
Request samples
application/json
{
  • "newPassword": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "oldPassword": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    }
}
Response samples
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "answer": "string",
    • "question": "string"
    }
}

Change Recovery Question
CORS
OAuth 2.0: okta.users.manage

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
path Parameters
userId
required
string
Request Body schema: application/json
object (PasswordCredential)
object (PasswordCredentialHash)
algorithm
string (PasswordCredentialHashAlgorithm)
Enum: "BCRYPT" "MD5" "SHA-1" "SHA-256" "SHA-512"
salt
string
saltOrder
string
value
string
workFactor
integer
object (PasswordCredentialHook)
type
string
value
string <password>
object (AuthenticationProvider)
name
string
type
string (AuthenticationProviderType)
Enum: "ACTIVE_DIRECTORY" "FEDERATION" "IMPORT" "LDAP" "OKTA" "SOCIAL"
object (RecoveryQuestionCredential)
answer
string
question
string
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/change_recovery_question
Request samples
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "answer": "string",
    • "question": "string"
    }
}
Response samples
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "answer": "string",
    • "question": "string"
    }
}

Initiate Forgot Password
CORS
OAuth 2.0: okta.users.manage

Initiates the forgot password flow. Generates a one-time token (OTT) that can be used to reset a user's password.

Request
path Parameters
userId
required
string
query Parameters
sendEmail
boolean
Default: true
Responses
200

Reset url

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/forgot_password
Request samples
Response samples
application/json
{
  • "resetPasswordUrl": "string"
}

Reset Password with Recovery Question
CORS
OAuth 2.0: okta.users.manage

Resets the user's password to the specified password if the provided answer to the recovery question is correct

Request
path Parameters
userId
required
string
query Parameters
sendEmail
boolean
Default: true
Request Body schema: application/json
object (PasswordCredential)
object (PasswordCredentialHash)
algorithm
string (PasswordCredentialHashAlgorithm)
Enum: "BCRYPT" "MD5" "SHA-1" "SHA-256" "SHA-512"
salt
string
saltOrder
string
value
string
workFactor
integer
object (PasswordCredentialHook)
type
string
value
string <password>
object (AuthenticationProvider)
name
string
type
string (AuthenticationProviderType)
Enum: "ACTIVE_DIRECTORY" "FEDERATION" "IMPORT" "LDAP" "OKTA" "SOCIAL"
object (RecoveryQuestionCredential)
answer
string
question
string
Responses
200

Credentials

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/forgot_password_recovery_question
Request samples
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "answer": "string",
    • "question": "string"
    }
}
Response samples
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "answer": "string",
    • "question": "string"
    }
}

List all User Grants
CORS
OAuth 2.0: okta.users.read

Lists all grants for the specified user

Request
path Parameters
userId
required
string
query Parameters
scopeId
string
expand
string
after
string
limit
integer <int32>
Default: 20
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/grants
Request samples
Response samples
application/json
[
  • {
    • "clientId": "string",
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": {
      },
    • "id": "string",
    • "issuer": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "scopeId": "string",
    • "source": "ADMIN",
    • "status": "ACTIVE",
    • "userId": "string",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Revoke all User Grants
CORS
OAuth 2.0: okta.users.manage

Revokes all grants for a specified user

Request
path Parameters
userId
required
string
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/grants
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Retrieve a User Grant
CORS
OAuth 2.0: okta.users.read

Retrieves a grant for the specified user

Request
path Parameters
userId
required
string
grantId
required
string
query Parameters
expand
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/grants/{grantId}
Request samples
Response samples
application/json
{
  • "clientId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "createdBy": {
    • "id": "string",
    • "type": "string"
    },
  • "id": "string",
  • "issuer": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "scopeId": "string",
  • "source": "ADMIN",
  • "status": "ACTIVE",
  • "userId": "string",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "property1": { },
    • "property2": { }
    }
}

Revoke a User Grant
CORS
OAuth 2.0: okta.users.manage

Revokes one grant for a specified user

Request
path Parameters
userId
required
string
grantId
required
string
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/grants/{grantId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

List all Groups
CORS
OAuth 2.0: okta.users.read

Lists all groups of which the user is a member

Request
path Parameters
userId
required
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/groups
Request samples
Response samples
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "objectClass": [
      ],