Application Users

Application user operations

List all assigned 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
q
string
query_scope
string
after
string

specifies the pagination cursor for the next page of assignments

limit
integer <int32>
Default: -1

specifies the number of results for a page

filter
string
expand
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/apps/{appId}/users
Request samples
Response samples
application/json
[
  • {
    • "created": "2014-06-24T15:27:59.000Z",
    • "credentials": {
      },
    • "externalId": "70c14cc17d3745e8a9f98d599a68329c",
    • "id": "00u11z6WHMYCGPCHCRFK",
    • "lastSync": "2014-06-24T15:27:59.000Z",
    • "lastUpdated": "2014-06-24T15:28:14.000Z",
    • "passwordChanged": "2014-06-24T15:27:59.000Z",
    • "profile": {
      },
    • "scope": "USER",
    • "status": "ACTIVE",
    • "statusChanged": "2014-06-24T15:28:14.000Z",
    • "syncState": "SYNCHRONIZED",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Assign a User
OAuth 2.0: okta.apps.manage

Assigns a user to an app with 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.

Notes:

  • You need to specify the id and omit the credentials parameter in the request body only for signOnMode or authentication schemes (credentials.scheme) that don't require credentials.
  • You can only specify profile properties that aren't defined by profile mappings when Universal Directory is enabled.
  • If your SSO app requires a profile but doesn't have provisioning enabled, you need to add a profile to the request body.
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. The authentication scheme of the app determines whether a username or password can be assigned to a user.

object (AppUserPasswordCredential)

Specifies a password for a user. 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

Username for the app

id
string

Unique identifier of the App User object (only required for apps with signOnMode or authentication schemes that don't require credentials)

object (AppUserProfile)

App user profiles are app-specific and can be customized by the Profile Editor in the Admin Console. SSO apps typically don't support app user profiles, while apps with user provisioning features have app-specific profiles. 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.

property name*
additional property
object
scope
required
string

Toggles the assignment between user or group scope

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
{
  • "credentials": {
    • "password": {
      },
    • "userName": "testuser"
    },
  • "id": "00u11z6WHMYCGPCHCRFK",
  • "profile": {
    • "property1": { },
    • "property2": { }
    },
  • "scope": "USER"
}
Response samples
application/json
{
  • "created": "2014-06-24T15:27:59.000Z",
  • "credentials": {
    • "password": { },
    • "userName": "testuser"
    },
  • "externalId": "70c14cc17d3745e8a9f98d599a68329c",
  • "id": "00u11z6WHMYCGPCHCRFK",
  • "lastSync": "2014-06-24T15:27:59.000Z",
  • "lastUpdated": "2014-06-24T15:28:14.000Z",
  • "passwordChanged": "2014-06-24T15:27:59.000Z",
  • "profile": {
    • "property1": { },
    • "property2": { }
    },
  • "scope": "USER",
  • "status": "ACTIVE",
  • "statusChanged": "2014-06-24T15:28:14.000Z",
  • "syncState": "SYNCHRONIZED",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "app": {
      },
    • "user": {
      }
    }
}

Retrieve an assigned User
OAuth 2.0: okta.apps.read

Retrieves a specific user assignment for app by id

Request
path Parameters
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
userId
required
string

ID of an existing Okta user

query Parameters
expand
string
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
{
  • "created": "2014-06-24T15:27:59.000Z",
  • "credentials": {
    • "password": { },
    • "userName": "testuser"
    },
  • "externalId": "70c14cc17d3745e8a9f98d599a68329c",
  • "id": "00u11z6WHMYCGPCHCRFK",
  • "lastSync": "2014-06-24T15:27:59.000Z",
  • "lastUpdated": "2014-06-24T15:28:14.000Z",
  • "passwordChanged": "2014-06-24T15:27:59.000Z",
  • "profile": {
    • "property1": { },
    • "property2": { }
    },
  • "scope": "USER",
  • "status": "ACTIVE",
  • "statusChanged": "2014-06-24T15:28:14.000Z",
  • "syncState": "SYNCHRONIZED",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "app": {
      },
    • "user": {
      }
    }
}

Update an App Profile for an assigned User
OAuth 2.0: okta.apps.manage

Updates a user's profile for an application

Request
path Parameters
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
userId
required
string

ID of an existing Okta user

Request Body schema: application/json
required
object (AppUserCredentials)

Specifies a user's credentials for the app. The authentication scheme of the app determines whether a username or password can be assigned to a user.

object (AppUserPasswordCredential)

Specifies a password for a user. 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

Username for the app

id
string

Unique identifier of the App User object (only required for apps with signOnMode or authentication schemes that don't require credentials)

object (AppUserProfile)

App user profiles are app-specific and can be customized by the Profile Editor in the Admin Console. SSO apps typically don't support app user profiles, while apps with user provisioning features have app-specific profiles. 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.

property name*
additional property
object
scope
required
string

Toggles the assignment between user or group scope

Enum: "USER" "GROUP"
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": {
    • "password": {
      },
    • "userName": "testuser"
    },
  • "id": "00u11z6WHMYCGPCHCRFK",
  • "profile": {
    • "property1": { },
    • "property2": { }
    },
  • "scope": "USER"
}
Response samples
application/json
{
  • "created": "2014-06-24T15:27:59.000Z",
  • "credentials": {
    • "password": { },
    • "userName": "testuser"
    },
  • "externalId": "70c14cc17d3745e8a9f98d599a68329c",
  • "id": "00u11z6WHMYCGPCHCRFK",
  • "lastSync": "2014-06-24T15:27:59.000Z",
  • "lastUpdated": "2014-06-24T15:28:14.000Z",
  • "passwordChanged": "2014-06-24T15:27:59.000Z",
  • "profile": {
    • "property1": { },
    • "property2": { }
    },
  • "scope": "USER",
  • "status": "ACTIVE",
  • "statusChanged": "2014-06-24T15:28:14.000Z",
  • "syncState": "SYNCHRONIZED",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "app": {
      },
    • "user": {
      }
    }
}

Unassign an App User
OAuth 2.0: okta.apps.manage

Unassigns a user from an application

Request
path Parameters
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
userId
required
string

ID of an existing Okta user

query Parameters
sendEmail
boolean
Default: false
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": [ ]
}