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

Sorting is done in ASCII sort order (that is, by ASCII character value), but isn't case sensitive.

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

Legal Disclaimer
After a user is added to the Okta directory, they receive an activation email. As part of signing up for this service, you agreed not to use Okta's service/product to spam and/or send unsolicited messages. Please refrain from adding unrelated accounts to the directory as Okta is not responsible for, and disclaims any and all liability associated with, the activation email's content. You, and you alone, bear responsibility for the emails sent to any recipients.

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

The human-readable description of the User Type

displayName
required
string

The human-readable name of the User Type

name
required
string

The name of the User Type. The name must start with A-Z or a-z and contain only A-Z, a-z, 0-9, or underscore (_) characters. This value becomes read-only after creation and can't be updated.

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",
    • "property1": null,
    • "property2": null
    },
  • "type": {
    • "description": "string",
    • "displayName": "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",
    • "property1": null,
    • "property2": null
    },
  • "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": {
    • "self": {
      }
    }
}

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

Retrieves a user from your Okta organization

Request
path Parameters
userId
required
string
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",
    • "property1": null,
    • "property2": null
    },
  • "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": {
    • "self": {
      }
    }
}

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",
    • "property1": null,
    • "property2": null
    }
}
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",
    • "property1": null,
    • "property2": null
    },
  • "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": {
    • "self": {
      }
    }
}

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
status
string (UserStatus)
Enum: "ACTIVE" "DEPROVISIONED" "LOCKED_OUT" "PASSWORD_EXPIRED" "PROVISIONED" "RECOVERY" "STAGED" "SUSPENDED"
transitioningToStatus
string (UserStatus)
Enum: "ACTIVE" "DEPROVISIONED" "LOCKED_OUT" "PASSWORD_EXPIRED" "PROVISIONED" "RECOVERY" "STAGED" "SUSPENDED"
object (UserType)
description
string

The human-readable description of the User Type

displayName
required
string

The human-readable name of the User Type

name
required
string

The name of the User Type. The name must start with A-Z or a-z and contain only A-Z, a-z, 0-9, or underscore (_) characters. This value becomes read-only after creation and can't be updated.

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",
    • "property1": null,
    • "property2": null
    },
  • "status": "ACTIVE",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "description": "string",
    • "displayName": "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",
    • "property1": null,
    • "property2": null
    },
  • "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": {
    • "self": {
      }
    }
}

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 User Blocks
CORS
OAuth 2.0: okta.users.read

Lists information about how the user is blocked from accessing their account

Request
path Parameters
userId
required
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/blocks
Request samples
Response samples
application/json
[
  • {
    • "type": "DEVICE_BASED",
    • "appliesTo": "UNKNOWN_DEVICES"
    }
]

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

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
tokenId
required
string

id of Token

Example: sHHSth53yJAyNSTQKDJZ
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": {
    • "self": {
      }
    }
}

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

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
tokenId
required
string

id of Token

Example: sHHSth53yJAyNSTQKDJZ
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" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)
Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer
keySize
integer
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" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)
Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer
keySize
integer
salt
string
saltOrder
string
value
string
workFactor
integer
object (PasswordCredentialHook)
type
string
value
string <password>
revokeSessions
boolean
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"
    },
  • "revokeSessions": true
}
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" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)
Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer
keySize
integer
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" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)
Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer
keySize
integer
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",