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": {
      },
    • "_links": {}
    }
]
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",