Grants

Grants represent an assignment or revocation of entitlements or entitlement bundles to a user. A user 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 request
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage

Creates a grant request

Request
Request Body schema: application/json
required

The writable attributes of a grant

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

Grant a bundle to a user

{
  • "grantType": "ENTITLEMENT-BUNDLE",
  • "entitlementBundleId": "enbfxqCAJWWGELFTYCCC",
  • "actor": "ACCESS_REQUEST",
  • "targetPrincipal": {
    • "externalId": "00ufxqCAJWWGELFTYCCC",
    • "type": "OKTA_USER"
    }
}
Response samples
application/json

Grant a bundle to a user

{
  • "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
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read

Lists grants for your organization. The filter expression (?filter=) is required to retrieve grants for a specific resource.

Supported filters are:

  • targetResourceOrn: string in orn format. target.externalId and target.type can also be used as an alternative but is not preferred.
  • targetPrincipalOrn: string in orn format. targetPrincipal.externalId and targetPrincipal.type can also be used as an alternative but is not preferred.
  • entitlementBundleId: string
  • entitlements.id: string
  • entitlements.values.id: string

Pagination parameters are accepted, and standard link headers are in the response.

Only active grants will be returned in the response.

By default, results are sorted by id.

Request
query Parameters
after
string non-empty

The after cursor provided by a prior request.

filter
required
string <scim-filter>

Apply various filters by using supported grants filtering properties. List of grants require either target.externalId and target.type, or targetResourceOrn to filter grants for a specific resource.

Note: Query parameter percent encoding is required. See Percent-encoding

Examples:
Query param: ?filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND targetPrincipal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND targetPrincipal.type eq "OKTA_USER"
filter=target.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20target.type%20eq%20%22APPLICATION%22%20AND%20targetPrincipal.externalId%20eq%20%2200ub0oNGTSWTBKOLGLNR%22%20AND%20targetPrincipal.type%20eq%20%22OKTA_USER%22
Query param: ?filter=targetResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND targetPrincipalOrn eq "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR"
filter=targetResourceOrn%20eq%20%22orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ%22%20AND%20targetPrincipalOrn%20eq%20%22orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR%22
Query param: ?filter=targetResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ"
filter=targetResourceOrn%20eq%20%22orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ%22
Query param: ?filter=targetResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND entitlementBundleId eq "08ab2db568c7c300079fefd0"
filter=targetResourceOrn%20eq%20%22orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ%22%20AND%20entitlementBundleId%20eq%20%2208ab2db568c7c300079fefd0%22
Query param: ?filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND entitlements.values.id eq "entfxqCAJWWFTFUUYBBB"
filter=target.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20target.type%20eq%20%22APPLICATION%22%20AND%20entitlements.values.id%20eq%20%22entfxqCAJWWFTFUUYBBB%22
Query param: ?filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION" AND entitlements.id eq "espfxqCAJWWFTFUUYKKK"
filter=target.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20target.type%20eq%20%22APPLICATION%22%20AND%20entitlements.id%20eq%20%22espfxqCAJWWFTFUUYKKK%22
Query param: ?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 "08ab2db568c7c300079fefd0")
filter=target.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20target.type%20eq%20%22APPLICATION%22%20AND%20(entitlements.values.id%20eq%20%22entfxqCAJWWFTFUUYBBB%22%20OR%20entitlements.values.id%20eq%20%22entfxqCAJWWFTFUUYXXX%22%20OR%20entitlementBundleId%20eq%20%2208ab2db568c7c300079fefd0%22)
include
Array of strings

The include filter adds additional properties in the response.

Items Enum: "full_entitlements" "metadata" Examples:
Query param: ?include=full_entitlements
include=full_entitlements
Query param: ?include=metadata
include=metadata
limit
integer [ 1 .. 200 ]
Default: 20

The maximum number of records that will be returned in a given result.

Responses
200

Get grants

400

An invalid request to list grants

401

When authentication fails

403

When authorization fails

404

When the requested resource was not 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
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read
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 filter adds additional properties in the response.


Items Enum: "full_entitlements" "metadata"   Examples: 
Query param: ?include=full_entitlements 
include=full_entitlements
Query param: ?include=metadata 
include=metadata
Responses 
200
Get grant


401
When authentication fails


403
When authorization fails


404
When the requested resource was not 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
Grant a bundle to a user


{
  • "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
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage
Replaces a grant with a specific id. Currently only supported for CUSTOM grant type.


Updates can only be made to entitlements for 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 writable attributes of a grant


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 the supported-resources endpoint for reference


 
targetResourceOrn
required
string <okta-resource-orn> 
The Okta App instance id in ORN format


See the supported-resources endpoint for reference


 
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


 
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": "0obfxqCAJWWGELFTYASJ",
      • "values": [
        ]
      },
    • {
      • "id": "0obfxqCAJWWGELFTYASJ",
      • "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": "0obfxqCAJWWGELFTYASJ",
      • "values": [
        ]
      },
    • {
      • "id": "0obfxqCAJWWGELFTYASJ",
      • "values": [
        ]
      }
    ],
  • "status": "ACTIVE",
  • "_links": {}
}