Application Users

The Application Users API provides operations to manage app users and their assignments. The object returned from assigning a user to an app is known as the application user.

You can assign users to apps for:

  • SSO only
  • SSO and provisioning

List all application users
OAuth 2.0:
  • okta.apps.read

Lists all assigned users for an app

Request
path Parameters
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
query Parameters
after
string

Specifies the pagination cursor for the next page of results. Treat this as an opaque value obtained through the next link relationship. See Pagination.

Example: after=16275000448691
limit
integer <int32> [ 1 .. 500 ]
Default: 50

Specifies the number of objects to return per page. If there are multiple pages of results, the Link header contains a next link that you need to use as an opaque value (follow it, don't parse it). See Pagination.

q
string

Specifies a filter for the list of application users returned based on their profile attributes. The value of q is matched against the beginning of the following profile attributes: userName, firstName, lastName, and email. This filter only supports the startsWith operation that matches the q string against the beginning of the attribute values.

Note: For OIDC apps, user profiles don't contain the firstName or lastName attributes. Therefore, the query only matches against the userName or email attributes.

Example: q=sam
expand
string

An optional query parameter to return the corresponding User object in the _embedded property. Valid value: user

Example: expand=user
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/apps/{appId}/users
Request samples 
Response samples 
application/json
[]
Assign an application user
OAuth 2.0: 
  • okta.apps.manage
Assigns a user to an app for:


    

  • SSO only
    
Assignments to SSO apps typically don't include a user profile.
However, if your SSO app requires a profile but doesn't have provisioning enabled, you can add profile attributes in the request body.
    

    • 

  • SSO and provisioning
    
Assignments to SSO and provisioning apps typically include credentials and an app-specific profile.
Profile mappings defined for the app are applied first before applying any profile properties that are specified in the request body.
    

    

    Notes:
    

      

    • When Universal Directory is enabled, you can only specify profile properties that aren't defined in profile mappings.
      • 

    • Omit mapped properties during assignment to minimize assignment errors.
      • 

    

    

    • 



Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Request Body schema: application/json
required
id
required
string
Unique identifier for the Okta user


 
object (AppUserCredentials) 
Specifies a user's credentials for the app.
This parameter can be omitted for apps with sign-on mode (signOnMode) or authentication schemes (credentials.scheme) that don't require credentials.


 
object (AppUserPasswordCredential) 
The user's password. This is a write-only property. An empty password object is returned to indicate that a password value exists.


 
value
string <password> 
Password value


 
userName
string  [ 1 .. 100 ] characters 
The user's username in the app




Note: The userNameTemplate in the application object defines the default username generated when a user is assigned to that app.
If you attempt to assign a username or password to an app with an incompatible authentication scheme, the following error is returned:
"Credentials should not be set on this resource based on the scheme."




 
object (AppUserProfile) 
Specifies the default and custom profile properties for a user.
Properties that are visible in the Admin Console for an app assignment can also be assigned through the API.
Some properties are reference properties that are imported from the target app and can't be configured.
See profile.


 
property name*
additional property
any
 
scope
string
Indicates if the assignment is direct (USER) or by group membership (GROUP).


 Enum: "USER" "GROUP"  
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/apps/{appId}/users
Request samples 
application/json
{
  • "id": "00ud4tVDDXYVKPXKVLCO",
  • "scope": "USER",
  • "credentials": {
    • "userName": "rae.cloud@example.com"
    }
}
Response samples 
application/json
{
  • "id": "00ud4tVDDXYVKPXKVLCO",
  • "externalId": null,
  • "created": "2024-01-27T03:52:45.000Z",
  • "lastUpdated": "2024-01-27T03:52:45.000Z",
  • "scope": "USER",
  • "status": "ACTIVE",
  • "statusChanged": "2024-01-27T03:52:45.000Z",
  • "passwordChanged": null,
  • "syncState": "DISABLED",
  • "credentials"": {
    • "userName": "rae.cloud@example.com"
    },
  • "profile": {
    • "street_address": null,
    • "country": null,
    • "website": null,
    • "zoneinfo": "America/Los_Angeles",
    • "birthdate": null,
    • "gender": null,
    • "formatted": null,
    • "profile": null,
    • "locality": null,
    • "given_name": "Rae",
    • "middle_name": null,
    • "locale": "en_US",
    • "picture": null,
    • "name": "Rae Cloud",
    • "nickname": null,
    • "phone_number": null,
    • "region": null,
    • "postal_code": null,
    • "family_name": "Cloud",
    • "email": "rae.cloud@example.com"
    },
  • "_links": {}
}
Retrieve an application user
OAuth 2.0: 
  • okta.apps.read
Retrieves a specific user assignment for a specific app


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
userId
required
string
ID of an existing Okta user


 
 Example:  00u13okQOVWZJGDOAUVR
query Parameters
expand
string
An optional query parameter to return the corresponding User object in the _embedded property.
Valid value: user


 
 Example:  expand=user
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/apps/{appId}/users/{userId}
Request samples 
Response samples 
application/json
{}
Update an application user
OAuth 2.0: 
  • okta.apps.manage
Updates the profile or credentials of a user assigned to an app


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
userId
required
string
ID of an existing Okta user


 
 Example:  00u13okQOVWZJGDOAUVR
Request Body schema: application/json
required
One of:
Updates the assigned user credentials


object (AppUserCredentials) 
Specifies a user's credentials for the app.
This parameter can be omitted for apps with sign-on mode (signOnMode) or authentication schemes (credentials.scheme) that don't require credentials.


 
object (AppUserPasswordCredential) 
The user's password. This is a write-only property. An empty password object is returned to indicate that a password value exists.


 
value
string <password> 
Password value


 
userName
string  [ 1 .. 100 ] characters 
The user's username in the app




Note: The userNameTemplate in the application object defines the default username generated when a user is assigned to that app.
If you attempt to assign a username or password to an app with an incompatible authentication scheme, the following error is returned:
"Credentials should not be set on this resource based on the scheme."




 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/apps/{appId}/users/{userId}
Request samples 
application/json
{
  • "credentials": {
    • "userName": "rae.cloud@example.com",
    • "password": {
      }
    }
}
Response samples 
application/json
{
  • "id": "00ud4tVDDXYVKPXKVLCO",
  • "externalId": null,
  • "created": "2024-01-27T03:52:45.000Z",
  • "lastUpdated": "2024-01-27T05:15:30.000Z",
  • "scope": "USER",
  • "status": "ACTIVE",
  • "statusChanged": "2024-01-27T03:52:45.000Z",
  • "passwordChanged": "2024-01-27T05:15:30.000Z",
  • "syncState": "DISABLED",
  • "credentials"": {
    • "userName": "rae.cloud@example.com",
    • "password": { }
    },
  • "profile": {
    • "street_address": null,
    • "country": null,
    • "website": null,
    • "zoneinfo": "America/Los_Angeles",
    • "birthdate": null,
    • "gender": null,
    • "formatted": null,
    • "profile": null,
    • "locality": null,
    • "given_name": "Rae",
    • "middle_name": null,
    • "locale": "en_US",
    • "picture": null,
    • "name": "Rae Cloud",
    • "nickname": null,
    • "phone_number": null,
    • "region": null,
    • "postal_code": null,
    • "family_name": "Cloud",
    • "email": "rae.cloud@example.com"
    },
  • "_links": {}
}
Unassign an application user
OAuth 2.0: 
  • okta.apps.manage
Unassigns a user from an app


For directories like Active Directory and LDAP, they act as the owner of the user's credential with Okta delegating authentication (DelAuth) to that directory.
If this request is successful for a user when DelAuth is enabled, then the user is in a state with no password. You can then reset the user's password.




Important: This is a destructive operation. You can't recover the user's app profile. If the app is enabled for provisioning and configured to deactivate users, the user is also deactivated in the target app.




Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
userId
required
string
ID of an existing Okta user


 
 Example:  00u13okQOVWZJGDOAUVR
query Parameters
sendEmail
boolean
 Default:  false
Sends a deactivation email to the administrator if true


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/apps/{appId}/users/{userId}
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": [ ]
}