User Grants

The User Grants API provides operations to manage user consent Grants in your org.

A consent represents a user's explicit permission to allow an app to access resources protected by scopes. Consent grants are different from tokens because a consent can outlast a token, and there can be multiple tokens with varying sets of scopes derived from a single consent. When an application comes back and needs to get a new access token, it may not need to prompt the user for consent if they've already consented to the specified scopes. Consent grants remain valid until the user manually revokes them, or until the user, application, authorization server or scope is deactivated or deleted.

Hint: For all grant operations, you can use me instead of the userId in an endpoint that contains /users, in an active session with no SSWS token (API token). For example: https://${yourOktaDomain}/api/v1/users/me/grants returns all the grants for the active session user.

Note: Some browsers have begun blocking third-party cookies by default, disrupting Okta functionality in certain flows. For more information, see FAQ: How Blocking Third Party Cookies Can Potentially Impact Your Okta Environment.

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

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
query Parameters
expand
string

Valid value: scope. If specified, scope details are included in the _embedded attribute.

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.

limit
integer <int32> [ 1 .. 200 ]
Default: 20

Specifies the number of tokens to return

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

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

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
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 User Grants
CORS
OAuth 2.0: okta.users.read

Lists all Grants for the specified user

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
query Parameters
scopeId
string

The scope ID to filter on

expand
string

Valid value: scope. If specified, scope details are included in the _embedded attribute.

Example: expand=scope
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.

limit
integer <int32> [ 1 .. 200 ]
Default: 20

Specifies the number of grants to return

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/grants
Request samples
Response samples
application/json
[]

Revoke all User Grants
CORS
OAuth 2.0: okta.users.manage

Revokes all Grants for a specified User

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

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

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

Retrieves a Grant for the specified User

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
grantId
required
string

Grant ID

Example: iJoqkwx50mrgX4T9LcaH
query Parameters
expand
string

Valid value: scope. If specified, scope details are included in the _embedded attribute.

Example: expand=scope
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/grants/{grantId}
Request samples
Response samples
application/json
{}

Revoke a User Grant
CORS
OAuth 2.0: okta.users.manage

Revokes one Grant for a specified User

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
grantId
required
string

Grant ID

Example: iJoqkwx50mrgX4T9LcaH
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

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