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

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


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