Grants

Grants represent an assignment or revocation of entitlements or entitlement bundles to a principal. A principal can have multiple grants.

Grant types can have different behavior characteristics.

Base

A principal and resource can only have a single base grant. Creating a base grant type replaces all other existing grants. The following grant types are available:

  • POLICY: Creates a grant for a principal driven by existing policy rules defined for the app.
  • CUSTOM: Creates a grant for a principal with specific entitlement and respective values.

Additive

A principal entitlement can have multiple additive grant types. These are applied based on the order that they were granted. Currently, only the following grant type is available:

  • ENTITLEMENT-BUNDLE: Creates a grant for a user with a specific entitlement bundle.

See Entitlement Management.

Create a grant
Beta
OAuth 2.0 scopes:
  • okta.governance.entitlements.manage
Admin roles:
  • APP_ADMIN

Creates a grant request with a specific grant type (grantType)

Request
Request Body schema: application/json
required

The grant request parameters depend on the selected grantType

entitlementBundleId
required
string <entitlement-bundle-id> = 20 characters

The entitlement bundle id

grantType
required
string

Additive grant type for entitlement bundle.

required
object

A representation of a principal

action
string
Default: "ALLOW"

The action to be taken for a grant

Enum: "ALLOW" "DENY"
actor
string
Default: "API"

The actor sending the grant request

Enum: "ACCESS_REQUEST" "ADMIN" "API" "NONE"
object

Scheduler specific settings applicable to a grant.

Responses
201

A successful grant creation operation

400

An invalid request to create an entitlement bundle

401

When authentication fails

403

When authorization fails

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

post/governance/api/v1/grants
Request samples
application/json
{
  • "grantType": "ENTITLEMENT-BUNDLE",
  • "entitlementBundleId": "enbfxqCAJWWGELFTYCCC",
  • "actor": "ACCESS_REQUEST",
  • "targetPrincipal": {
    • "externalId": "00ufxqCAJWWGELFTYCCC",
    • "type": "OKTA_USER"
    }
}
Response samples
application/json
{
  • "id": "0ggb0oNGTSWTBKOLGLNR",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "grantType": "ENTITLEMENT-BUNDLE",
  • "entitlementBundleId": "enbfxqCAJWWGELFTYCCC",
  • "action": "ALLOW",
  • "actor": "ACCESS_REQUEST",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "targetPrincipalOrn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR",
  • "targetPrincipal": {
    • "externalId": "00ub0oNGTSWTBKOLGLNR",
    • "type": "OKTA_USER"
    },
  • "status": "ACTIVE",
  • "_links": {}
}

List all grants
Beta
OAuth 2.0 scopes:
  • okta.governance.entitlements.read
Admin roles:
  • APP_ADMIN

Lists active grants (status="ACTIVE") for your org.

The filter expression (?filter=) is required.

Pagination parameters are accepted. Standard link headers are in the response.

By default, results are sorted by id.

Request
query Parameters
after
string non-empty

The pagination cursor that points to the last record of the previous request

filter
required
string <scim-filter>

A filter expression that returns entries based on the following properties:

  • targetResourceOrn (alternatively, you can use target.externalId and target.type for a specific resource )
  • targetPrincipalOrn (alternatively, you can use targetPrincipal.externalId and targetPrincipal.type for a specific principal)
  • entitlementBundleId
  • entitlements.id
  • entitlements.values.id
  • action

The eq operator is supported for these properties. The AND and OR logical operators are supported for combining multiple expressions.

Note: Query parameter percent encoding is required. See Special characters.

Examples:
filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND targetPrincipal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND targetPrincipal.type eq "OKTA_USER"
filter=targetResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND targetPrincipalOrn eq "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR"
filter=targetResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ"
filter=targetResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND entitlementBundleId eq "enbllojq9J9J105DL1d6"
filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND entitlements.values.id eq "entfxqCAJWWFTFUUYBBB"
filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND entitlements.id eq "espfxqCAJWWFTFUUYKKK"
filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND (entitlements.values.id eq "entfxqCAJWWFTFUUYBBB" OR entitlements.values.id eq "entfxqCAJWWFTFUUYXXX" OR entitlementBundleId eq "enbllojq9J9J105DL1d6")
filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND action eq "ALLOW"
include
Array of strings

The include parameter adds additional properties to the response.

Items Enum: Description
full_entitlements

Include complete entitlements in the response

metadata

Include metadata such as collection generating the grant in the response

Examples:
include=full_entitlements
include=metadata
limit
integer [ 1 .. 200 ]
Default: 20

The maximum number of records returned in a response

Responses
200

Get grants

400

An invalid request to list grants

401

When authentication fails

403

When authorization fails

404

When the requested resource wasn't found

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

get/governance/api/v1/grants
Request samples 
Response samples 
application/json
A principal user can have active POLICY grants and ENTITLEMENT-BUNDLE grants. This is common when an entitlement policy grants a user an entitlement, and then a user requests access to a specific entitlement bundle at a later date.


{}
Retrieve a grant
Beta
OAuth 2.0 scopes: 
  • okta.governance.entitlements.read
Admin roles: 
  • APP_ADMIN
Retrieves the full detail of a specific grant


Request 
path Parameters
grantId
required
string
The id of the grant


 
query Parameters
include
Array of strings
The include parameter adds additional properties to the response.


Items Enum: Description
full_entitlements
Include complete entitlements in the response


metadata
Include metadata such as collection generating the grant in the response


  Examples: 
include=full_entitlements
include=metadata
Responses 
200
Get grant


401
When authentication fails


403
When authorization fails


404
When the requested resource wasn't found


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


get/governance/api/v1/grants/{grantId}
Request samples 
Response samples 
application/json
{
  • "id": "0ggb0oNGTSWTBKOLGLNR",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "grantType": "ENTITLEMENT-BUNDLE",
  • "entitlementBundleId": "enbfxqCAJWWGELFTYCCC",
  • "action": "ALLOW",
  • "actor": "ACCESS_REQUEST",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "targetPrincipalOrn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR",
  • "targetPrincipal": {
    • "externalId": "00ub0oNGTSWTBKOLGLNR",
    • "type": "OKTA_USER"
    },
  • "status": "ACTIVE",
  • "_links": {}
}
Replace a grant
Beta
OAuth 2.0 scopes: 
  • okta.governance.entitlements.manage
Admin roles: 
  • APP_ADMIN
Replaces the entitlements of a grant with a specific id.


You can only replace objects in the entitlements array for a grant with the CUSTOM grant type.
This may result in changes to principal entitlements.


Request 
path Parameters
grantId
required
string
The id of the grant


 
Request Body schema: application/json
required
The grant request parameters depend on the selected grantType


required
object
Links available on a single grant representation


 
action
required
string
 Default:  "ALLOW"
The action to be taken for a grant


 Enum: "ALLOW" "DENY"  
actor
required
string
 Default:  "API"
The actor sending the grant request


 Enum: "ACCESS_REQUEST" "ADMIN" "API" "NONE"  
grantType
required
string
Type of grant


 Enum: "CUSTOM" "ENTITLEMENT" "ENTITLEMENT-BUNDLE" "POLICY"  
id
required
string  non-empty 
Unique identifier for the object


 
status
required
string
The state of the particular grant setting


 Enum: "ACTIVE" "EXPIRED" "INACTIVE" "SCHEDULED"  
required
object
Representation of a resource


 
required
object
Representation of a principal


 
targetPrincipalOrn
required
string <okta-user-orn> 
The Okta user id in ORN format.


See Supported resources.


 
targetResourceOrn
required
string <okta-resource-orn> 
The Okta app instance, in ORN format.


See the ORN format for a specific app in Supported resouces.


 
entitlementBundleId
string <entitlement-bundle-id>   = 20 characters 
The entitlement bundle id


 
Array of objects
Collection of entitlements and associated value identifiers


 
object
Grant metadata properties


 
object
Scheduler specific settings applicable to a grant.


 
Responses 
200
A successful grant creation operation


400
An invalid request to create an entitlement bundle


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


put/governance/api/v1/grants/{grantId}
Request samples 
application/json
Update custom grant entitlements.


{
  • "id": "0ggb0oNGTSWTBKOLGLNR",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "grantType": "CUSTOM",
  • "action": "ALLOW",
  • "actor": "API",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "targetPrincipalOrn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR",
  • "targetPrincipal": {
    • "externalId": "00ub0oNGTSWTBKOLGLNR",
    • "type": "OKTA_USER"
    },
  • "entitlements": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "values": [
        ]
      },
    • {
      • "id": "esp4rg7fkom0c3AsX8g6",
      • "values": [
        ]
      }
    ],
  • "status": "ACTIVE",
  • "_links": {}
}
Response samples 
application/json
Grant a resource with custom entitlements


{
  • "id": "0ggb0oNGTSWTBKOLGLNR",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "grantType": "CUSTOM",
  • "action": "ALLOW",
  • "actor": "API",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "targetPrincipalOrn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR",
  • "targetPrincipal": {
    • "externalId": "00ub0oNGTSWTBKOLGLNR",
    • "type": "OKTA_USER"
    },
  • "entitlements": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "values": [
        ]
      },
    • {
      • "id": "esp4rg7fkom0c3AsX8g6",
      • "values": [
        ]
      }
    ],
  • "status": "ACTIVE",
  • "_links": {}
}
Update a grant
Beta
OAuth 2.0 scopes: 
  • okta.governance.entitlements.manage
Admin roles: 
  • APP_ADMIN
Updates a grant expiry date.


You can only update the scheduleSettings.expirationDate property for a grant.


Request 
path Parameters
grantId
required
string
The id of the grant


 
Request Body schema: application/json
required
Request parameters for a grant expiration date update


id
required
string  non-empty 
Unique identifier for the object


 
required
object
Scheduler specific settings applicable to a grant.


 
Responses 
200
A successful grant patch operation


400
An invalid request to patch expiration date for grant


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


patch/governance/api/v1/grants/{grantId}
Request samples 
application/json
Update grant's expiration date.


{
  • "id": "0ggb0oNGTSWTBKOLGLNR",
  • "scheduleSettings": {
    • "expirationDate": "2022-11-24T14:15:22Z"
    }
}
Response samples 
application/json
{
  • "id": "0ggb0oNGTSWTBKOLGLNR",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "grantType": "ENTITLEMENT-BUNDLE",
  • "entitlementBundleId": "enbfxqCAJWWGELFTYCCC",
  • "action": "ALLOW",
  • "actor": "API",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "targetPrincipalOrn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR",
  • "targetPrincipal": {
    • "externalId": "00ub0oNGTSWTBKOLGLNR",
    • "type": "OKTA_USER"
    },
  • "status": "ACTIVE",
  • "scheduleSettings": {
    • "expirationDate": "2022-11-24T14:15:22Z",
    • "timeZone": "America/Toronto"
    },
  • "_links": {}
}