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
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

id
required
string

Unique identifier for the Okta User

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"
    },
}

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

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"
    },
}

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": [ ]
}