On this page

Administrator Roles API

The Okta Administrator Roles API provides operations to manage both standard and custom administrative Role assignments for a User.

This document includes the operations of the standard Roles API and the Custom Roles API, and where they intersect.

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

Get started

Explore the Administrator Roles API: Run in Postman (opens new window)

Custom Role operations

These operations allow the creation and manipulation of Custom Roles as custom collections of permissions.

Create Role

POST /api/v1/iam/roles

Creates a Role with a custom collection of permissions

Request parameters

Parameter Description Param Type DataType Required
label The name given to the new Role Body String TRUE
description A description of the new Role Body String TRUE
permissions The permissions that the new Role grants Body Array of Permission names TRUE

Response parameters

A created Custom Role

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "label": "UserCreator",
      "description": "Create users",
      "permissions": [
        "okta.users.create",
        "okta.users.read",
        "okta.groups.read",
        "okta.users.userprofile.manage"
      ]
    }' "https://${yourOktaDomain}/api/v1/iam/roles"

Response example

{
  "id": "cr0Yq6IJxGIr0ouum0g3",
  "label": "UserCreator",
  "description": "Create users",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    }
  }
}

Get Role

GET /api/v1/iam/roles/${roleIdOrLabel}

Retrieves a Custom Role by its ID or label

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE

Response parameters

The requested Custom Role

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles/UserCreator"

Response example

{
  "id": "cr0Yq6IJxGIr0ouum0g3",
  "label": "UserCreator",
  "description": "Create users",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    }
  }
}

Update Role

PUT /api/v1/iam/roles/${roleIdOrLabel}

Updates a Custom Role's label or description by its ID or label

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE
label The updated label to apply to the Role Body String TRUE
description The updated description to apply to the Role Body String TRUE

Response parameters

The updated Custom Role

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "label": "UserCreator-Updated",
      "description": "Create users"
    }' \
"https://${yourOktaDomain}/api/v1/iam/roles/UserCreator"

Response example

{
  "id": "cr0Yq6IJxGIr0ouum0g3",
  "label": "UserCreator-Updated",
  "description": "Create users",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-08T16:20:57.000Z",
  "_links": {
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    }
  }
}

List roles

GET /api/v1/iam/roles

Lists all Custom Roles

Response parameters

A paginated list of Custom Roles

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles"

Response example

{
  "roles": [
    {
      "id": "cr0Yq6IJxGIr0ouum0g3",
      "label": "UserCreator",
      "description": "Create users",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "permissions": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions"
        },
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
        }
      }
    },
    {
      "id": "cr0Fw7HKcWIroo88m3r1",
      "label": "GroupMembershipManager",
      "description": "Manage group membership",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "permissions": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Fw7HKcWIroo88m3r1/permissions"
        },
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Fw7HKcWIroo88m3r1"
        }
      }
    }
  ],
  "_links": {
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles?after=cr0Fw7HKcWIroo88m3r1"
    }
  }
}

List permissions

GET /api/v1/iam/roles/${roleIdOrLabel}/permissions

Lists all permissions included in a Custom Role identified by its id or label

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE

Response parameters

An array of Permission types that identifies the Role by ${roleIdOrLabel} and provides a link to that Role

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions"

Response example

{
  "permissions": [
    {
      "label" : "okta.users.create",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "role": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
        },
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.create"
        }
      }
    },
    {
      "label" : "okta.users.read",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "role": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
        },
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.read"
        }
      }
    },
    {
      "label" : "okta.groups.read",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "role": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
        },
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.groups.read"
        }
      }
    },
    {
      "label" : "okta.users.userprofile.manage",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "role": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
        },
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.userprofile.manage"
        }
      }
    }
  ]
}

Create a Permission

POST /api/v1/iam/roles/${roleIdOrLabel}/permissions/${permissionType}

Creates a Permission on an existing Role

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE
permissionType Permission to add to the Role URL Permission name TRUE
conditions Conditions for further restricting a permission Body Condition object FALSE

Response parameters

HTTP/1.1 204 No Content

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.manage"

Response example

HTTP/1.1 204 No Content

Returns an error if the permission exists

HTTP/1.1 400 Bad Request

Update permission

PUT /api/v1/iam/roles/${roleIdOrLabel}/permissions/${permissionType}

Updates an existing permission in a Role

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE
permissionType Permission to update in the Role URL Permission name TRUE
conditions Conditions for further restricting a permission Body Condition object FALSE

NOTE: Conditions are only available for okta.users.read and okta.users.userprofile.manage

Response parameters

The updated Permission object

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.read"
-d '{
    "conditions": {
      "include": {
        "okta:ResourceAttribute/User/Profile": [
          "city",
          "state",
          "zipCode"
        ]
      }
    }
  }'

Response example

{
  "label" : "okta.users.read",
  "conditions": {
    "include": {
      "okta:ResourceAttribute/User/Profile": [
        "city",
        "state",
        "zipCode"
      ]
    }
  },
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.read"
    }
  }
}

Retrieve a permission

GET /api/v1/iam/roles/${roleIdOrLabel}/permissions/${permissionType}

Retrieves a permission from an existing Role

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE
permissionType Permission to retrieve from the Role URL Permission name TRUE

Response parameters

The requested Permission
Includes the conditions on the permission (if applicable)

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.manage"

Response example

{
  "label" : "okta.users.manage",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.manage"
    }
  }
}

Response example with Conditions

{
  "label" : "okta.users.read",
  "conditions": {
    "include": {
      "okta:ResourceAttribute/User/Profile": [
        "city",
        "state",
        "zipCode"
      ]
    }
  },
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.read"
    }
  }
}

Delete permission

DELETE /api/v1/iam/roles/${roleIdOrLabel}/permissions/${permissionType}

Deletes a permission from an existing Role

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE
permissionType Permission to remove from the Role URL Permission name TRUE

Response parameters

HTTP/1.1 204 No Content

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.manage"

Response example

HTTP/1.1 204 No Content

Delete Role

DELETE /api/v1/iam/roles/${roleIdOrLabel}

Deletes a Custom Role

Request parameters

Parameter Description Param Type DataType Required
roleIdOrLabel id or label of the Role URL String TRUE

Response parameters

HTTP/1.1 204 No Content

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/roles/UserCreator"

Response example

HTTP/1.1 204 No Content

Resource Set operations

These operations allow the creation and manipulation of Resource Sets as custom collections of resources. You can use Resource Sets to assign Custom Roles to administrators who are scoped to the designated resources.

Create Resource Set

POST /api/v1/iam/resource-sets

Creates a Resource Set with a custom collection of resources

Request parameters

Parameter Description Param Type DataType Required
label Unique name given to the new Resource Set Body String TRUE
description A description of the new Resource Set Body String TRUE
resources The endpoints that reference the resources to be included in the new Resource Set Body Array of URL TRUE

Response parameters

The created Resource Set

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "label": "SF-IT-People",
      "description": "People in the IT department of San Francisco",
      "resources": [
        "https://${yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3",
        "https://${yourOktaDomain}/api/v1/groups/00gu67DU2qNCjNZYO0g3/users",
        "https://${yourOktaDomain}/api/v1/users",
        "orn:${partition}:directory:${yourOrgId}:groups:00g4bjtkrsFSFhzB00g7"
      ]
    }' "https://${yourOktaDomain}/api/v1/iam/resource-sets"

Response example

{
  "id": "iamoJDFKaJxGIr0oamd9g",
  "label": "SF-IT-People",
  "description": "People in the IT department of San Francisco",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    },
    "resources": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    }
  }
}

Get Resource Set

GET /api/v1/iam/resource-sets/${resourceSetIdOrLabel}

Retrieves a Resource Set by its ID or Label

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel Unique ID or label of the Resource Set URL String TRUE

Response parameters

The requested Resource Set

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"

Response example

{
  "id": "iamoJDFKaJxGIr0oamd9g",
  "label": "SF-IT-People",
  "description": "People in the IT department of San Francisco",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    },
    "resources": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    }
  }
}

List all Resource Sets

GET /api/v1/iam/resource-sets

Lists all Resource Sets

Response parameters

A paginated list of Resource Sets

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets"

Response example

{
  "resource-sets": [
    {
      "id": "iamoJDFKaJxGIr0oamd9g",
      "label": "SF-IT-1",
      "description": "First San Francisco IT Resource Set",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
        },
        "resources": {
          "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources"
        },
        "bindings": {
          "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
        }
      }
    },
    {
      "id": "iamoJDFKaJxGIr0oamd0q",
      "label": "SF-IT-2",
      "description": "Second San Francisco IT Resource Set",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd0q"
        },
        "resources": {
          "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd0q/resources"
        },
        "bindings": {
          "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd0q/bindings"
        }
      }
    }
  ],
  "_links": {
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets?after=iamoJDFKaJxGIr0oamd0q"
    }
  }
}

Update Resource Set

PUT /api/v1/iam/resource-sets/${resourceSetIdOrLabel}

Updates the label and description of a Resource Set

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel Unique ID or label of the Resource Set URL String TRUE
label New unique name given to the Resource Set Body String TRUE
description New description of the Resource Set Body String TRUE

Response parameters

An updated Resource Set

Request example

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "label": "SF-IT-Staff",
      "description": "Staff in the IT department of San Francisco"
    }' "https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"

Response example

{
  "id": "iamoJDFKaJxGIr0oamd9g",
  "label": "SF-IT-Staff",
  "description": "Staff in the IT department of San Francisco",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-07T16:20:57.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    },
    "resources": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    }
  }
}

Delete Resource Set

DELETE /api/v1/iam/resource-sets/${resourceSetIdOrLabel}

Deletes a Resource Set and all its associated Bindings

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE

Response parameters

HTTP/1.1 204 No Content

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"

Response example

HTTP/1.1 204 No Content

Resource operations

These operations add, remove, and list the resources within a Resource Set.

Update resources

PATCH /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/resources

Updates resources to a Resource Set

Request parameters
Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE
additions The endpoints that reference the resources to be included in the new Resource Set Body Array of URL TRUE
Response parameters

An updated Resource Set

To view the list of resources, use the List resources operation.

Request example
curl -v -X PATCH \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "additions": [
        "https://${yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3",
        "https://${yourOktaDomain}/api/v1/groups/00gu67DU2qNCjNZYO0g3/users",
        "orn:${partition}:directory:${yourOrgId}:groups:00g4bjtkrsFSFhzB00g7"
      ]
    }' "https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources"
Response example
{
  "id": "iamoJDFKaJxGIr0oamd9g",
  "label": "SF-IT-Staff",
  "description": "Staff in the IT department of San Francisco",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-07T16:20:57.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    },
    "resources": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    }
  }
}

List resources

GET /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/resources

Lists the Resources that make up a Resource Set

Request parameters
Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE
Response parameters

A paginated array of Resources

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources"
Response example
{
  "resources": [
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "orn": "orn:{partition}:directory:{yourOrgId}:groups:00guaxWZ0AOa5NFAj0g3",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3"
        }
      }
    },
    {
      "id": "ire106riDrTYl4qA70g4",
      "orn": "orn:{partition}:directory:{yourOrgId}:groups:00gu67DU2qNCjNZYO0g3:contained_resources",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups/00gu67DU2qNCjNZYO0g3/users"
        }
      }
    },
    {
      "id": "irezvo4AwE2ngpMw40g3",
      "orn": "orn:{partition}:directory:{yourOrgId}:users",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/users"
        },
        "users": {
          "href": "https://{yourOktaDomain}/api/v1/users"
        }
      }
    },
    {
      "id": "ire2j4iDnxHhUFaZN0g4",
      "orn": "orn:{partition}:directory:{yourOrgId}:groups",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups"
        },
        "groups": {
          "href": "https://{yourOktaDomain}/api/v1/groups"
        }
      }
    }
  ],
  "_links": {
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources?after=irezvn1ZZxLSIBM2J0g3"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    }
  }
}

Delete a resource

DELETE /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/resources/${resourceId}

Removes a resource from a Resource Set

Request parameters
Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE
resourceId ID of the resource within the Resource Set URL String TRUE

The resourceId parameter is the ID that is obtained when resources are listed within the Resource Set. For example, if the resource object is:

    {
      "id": "ire106sQKoHoXXsAe0g4",
      "orn": "orn:{partition}:directory:{yourOrgId}:groups:00guaxWZ0AOa5NFAj0g3",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3"
        }
      }
    }

You can use ire106sQKoHoXXsAe0g4 as the resourceId to remove the Groups from the list of resources in the set.

Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/resources/ire106sQKoHoXXsAe0g4"
Response example
HTTP/1.1 204 No Content

Custom Role assignment operations

These operations allow the assignment and unassignment of Custom Roles. This is done by creating a Binding. A Binding represents an association where the bindingId identifies the Principal, Role, and Resource Set.

Create a new Binding

POST /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings

Assigns a Custom Role by creating a Binding between the Role and the admin that targets an existing Resource Set

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE
role ID of the Role Body String TRUE
members The hrefs that point to Users and/or Groups that receive the Role Body Array of hrefs TRUE

Response parameters

The following _links are returned:

  • self: Retrieves this Role's Binding within the Resource Set
  • bindings: Lists all Role Bindings in the Resource Set
  • resource-set: Retrieves the Resource Set

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "role": "cr0Yq6IJxGIr0ouum0g3",
      "members": [
        "https://${yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3"
      ]
}' "https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"

Response example

{
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    }
  }
}

Request example with client application

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "role": "cr0Yq6IJxGIr0ouum0g3",
      "members": [
        "https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4"
      ]
}' "https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"

Response example

{
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    }
  }
}

Add more Members to a Binding

PATCH /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings/${roleIdOrLabel}/members

Updates a Role Binding that is already created in a Resource Set with more Members

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the target Resource Set URL String TRUE
roleIdOrLabel ID or label of the Role to grant URL String TRUE
additions Array of hrefs that point to one or more Users and/or Groups that receive the Role Body Array of hrefs TRUE

Response parameters

The following _links are returned:

  • self: Retrieves this Role's Binding within the Resource Set
  • bindings: Lists all Role Bindings in the Resource Set
  • resource-set: Retrieves the Resource Set

Request example

curl -v -X PATCH \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "additions": [
        "https://${yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3",
        "https://${yourOktaDomain}/api/v1/users/00u67DU2qNCjNZYO0g3"
      ]
    }' "https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4/members"

Response example

{
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    }
  }
}

Request example with client application

curl -v -X PATCH \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "additions": [
        "https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4"
      ]
    }' "https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4/members"

Response example

{
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3"
    },
    "bindings": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    }
  }
}

List Members in a Binding

GET /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings/${roleIdOrLabel}/members

Lists all Members that are assigned to a Role in a Resource Set

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the target Resource Set URL String TRUE
roleIdOrLabel ID or label of the Role to identify the Binding URL String TRUE

Response parameters

A paginated list of Members

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4/members"

Response example

{
  "members": [
    {
      "id": "irb1qe6PGuMc7Oh8N0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/users/00uuk41Hjga5qGfQ30g3"
        }
      }
    }, {
      "id": "irb1q92TFAHzySt3x0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3"
        }
      }
    }
  ],
  "_links": {
    "binding": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/${resource-set-id}/bindings/${role-id-or-name}"
    },
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/${resource-set-id}/bindings/${role-id-or-name}/members?after=${last-member-id}"
    }
  }
}

Response example with client application

{
  "members": [
    {
      "id": "irb5vzkeQKc56r5G10g4",
      "created": "2022-12-14T00:00:00.000Z",
      "lastUpdated": "2022-12-14T00:00:00.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4"
        }
      }
    }
  ],
  "_links": {
    "binding": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/${resource-set-id}/bindings/${role-id-or-name}"
    },
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/${resource-set-id}/bindings/${role-id-or-name}/members?after=${last-member-id}"
    }
  }
}

Get a Member from a Binding

GET /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings/${roleIdOrLabel}/members/${memberId}

Retrieves a Member of a Role in a Resource Set

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the target Resource Set URL String TRUE
roleIdOrLabel ID or label of the Role to identify the Binding URL String TRUE
memberId ID of the Member within the Binding URL String TRUE

The memberId parameter is the ID that is obtained when Members are listed in a Binding. For example, if the Member object was:

{
  "id": "irb1qe6PGuMc7Oh8N0g4",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/users/00uuk41Hjga5qGfQ30g3"
    }
  }
}

Then irb1qe6PGuMc7Oh8N0g4 could be used as memberId to remove the User from the list of Members in the Binding.

Response parameters

The ID that represents the Binding and a link to the actual Member object, which could be a User or a Group

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4/members/irb1qe6PGuMc7Oh8N0g4"

Response example

{
  "id": "irb1qe6PGuMc7Oh8N0g4",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/users/00uuk41Hjga5qGfQ30g3"
    }
  }
}

Delete a Member from a Binding

DELETE /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings/${roleIdOrLabel}/members/${memberId}

Deletes a Member of a Role in a Resource Set

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the target Resource Set URL String TRUE
roleIdOrLabel ID or label of the Role to identify the Binding URL String TRUE
memberId ID of the Member in the Binding URL String TRUE

The memberId parameter is the ID that is obtained when Members are listed in a Binding. For example, if the Member object was:

{
  "id": "irb1qe6PGuMc7Oh8N0g4",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/users/00uuk41Hjga5qGfQ30g3"
    }
  }
}

Then irb1qe6PGuMc7Oh8N0g4 could be used as memberId to remove the User from the list of Members in the Binding.

Response parameters

HTTP/1.1 204 No Content

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4/members/irb1qe6PGuMc7Oh8N0g4"

Response example

HTTP/1.1 204 No Content

Retrieve Bindings

Get a Binding by Role ID or label

GET /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings/${roleIdOrLabel}

Retrieves a Binding from a Resource Set by its Role ID

Request parameters
Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE
roleIdOrLabel ID or label of the Role URL String TRUE
Response parameters

The id of the Role and the following _links:

  • self: Retrieves this Role's Binding within the Resource Set
  • bindings: Lists all paginated Role Bindings in the Resource Set
  • resource-set: Retrieves the Resource Set
Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4"
Response example
{
  "id": "cr0WxyzJxGIr0ouum0g4",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4"
    },
    "members": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4/members"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    }
  }
}

Get all Bindings in a Resource Set

GET /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings

Lists all the Bindings in a Resource Set

Request parameters
Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE
Response parameters

A paginated list of Bindings

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
Response example
{
  "roles": [
    {
      "id": "cr0WxyzJxGIr0ouum0g4",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0WxyzJxGIr0ouum0g4"
        },
        "members": {
          "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4/members"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    },
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings?after=cr0WxyzJxGIr0ouum0g4"
    }
  }
}

Delete a Binding

DELETE /api/v1/iam/resource-sets/${resourceSetIdOrLabel}/bindings/${roleIdOrLabel}

Deletes a Binding of a Role from a Resource Set

Request parameters

Parameter Description Param Type DataType Required
resourceSetIdOrLabel ID or label of the Resource Set URL String TRUE
roleIdOrLabel ID or label of the Role URL String TRUE

Response parameters

HTTP/1.1 204 No Content

Request example

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0WxyzJxGIr0ouum0g4"
Response example
HTTP/1.1 204 No Content

Role assignment operations

Grant third-party admin status to a User

POST /api/v1/users/${userId}/roles?disableNotifications=true

Grant third-party admin status to a Group

POST /api/v1/groups/${groupId}/roles?disableNotifications=true

You can grant third-party admin status by using an optional query parameter on the Administrator Roles API called disableNotifications.

You can grant third-party admin status when you assign a new role, or you can update an existing role assignment status by passing just the query parameter.

When this setting is enabled, the admins don't receive any of the default Okta administrator emails. These admins also don't have access to contact Okta Support and open support cases on behalf of your org.

List Users with Role Assignments

GET /api/v1/iam/assignees/users

Lists all the Users with Role Assignments

Request parameters
Parameter Description Param Type DataType Required
after Specifies the pagination cursor for the next page of targets Query String FALSE
limit Specifies the number of results for a page (default is 100) Query Number FALSE
Response parameters

Array of RoleAssignedUser

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/iam/assignees/users"
Response example
{
  "value": [
    {
      "id": "00u118oQYT4TBGuay0g4",
      "orn": "orn:okta:00o5rb5mt2H3d1TJd0h7:users:00u118oQYT4TBGuay0g4",
      "_links": {
        "self": {
          "href": "http://your-subdomain.okta.com/api/v1/users/00u118oQYT4TBGuay0g4"
        },
        "roles": {
          "href": "http://your-subdomain.okta.com/api/v1/users/00u118oQYT4TBGuay0g4/roles"
        }
      }
    }
  ],
  "_links": {
    "next": {
      "href": "http://your-subdomain.okta.com/api/v1/iam/assignees/users?after=00u118oQYT4TBGuay0g4&limit=1"
    }
  }
}

List Roles

List Roles assigned to a User

GET /api/v1/users/${userId}/roles

Lists all the Roles assigned to a User

Request parameters
Parameter Description Param Type DataType Required
userId ID of a User URL String TRUE
Response parameters

Array of Roles

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles"
Response example
[
    {
        "id": "IFIFAX2BIRGUSTQ",
        "label": "Application Administrator",
        "type": "APP_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:17:40.000Z",
        "lastUpdated": "2019-02-06T16:17:40.000Z",
        "assignmentType": "USER",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
            }
        }
    },
    {
        "id": "JBCUYUC7IRCVGS27IFCE2SKO",
        "label": "Help Desk Administrator",
        "type": "HELP_DESK_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:17:40.000Z",
        "lastUpdated": "2019-02-06T16:17:40.000Z",
        "assignmentType": "USER",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
            }
        }
    },
    {
        "id": "ra125eqBFpETrMwu80g4",
        "label": "Organization Administrator",
        "type": "ORG_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:17:40.000Z",
        "lastUpdated": "2019-02-06T16:17:40.000Z",
        "assignmentType": "USER",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
            }
        }
    },
    {
        "id": "gra25fapn1prGTBKV0g4",
        "label": "API Access Management Administrator",
        "type": "API_ACCESS_MANAGEMENT_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:20:57.000Z",
        "lastUpdated": "2019-02-06T16:20:57.000Z",
        "assignmentType": "GROUP",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/groups/00g1ousb3XCr9Dkr20g4"
            }
        }
    }
]
Response example with Custom Roles
[
    {
        "id": "IFIFAX2BIRGUSTQ",
        "label": "Application Administrator",
        "type": "APP_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:17:40.000Z",
        "lastUpdated": "2019-02-06T16:17:40.000Z",
        "assignmentType": "USER",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
            }
        }
    },
    {
        "id": "JBCUYUC7IRCVGS27IFCE2SKO",
        "label": "Help Desk Administrator",
        "type": "HELP_DESK_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:17:40.000Z",
        "lastUpdated": "2019-02-06T16:17:40.000Z",
        "assignmentType": "USER",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
            }
        }
    },
    {
        "id": "ra125eqBFpETrMwu80g4",
        "label": "Organization Administrator",
        "type": "ORG_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:17:40.000Z",
        "lastUpdated": "2019-02-06T16:17:40.000Z",
        "assignmentType": "USER",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
            }
        }
    },
    {
        "id": "gra25fapn1prGTBKV0g4",
        "label": "API Access Management Administrator",
        "type": "API_ACCESS_MANAGEMENT_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:20:57.000Z",
        "lastUpdated": "2019-02-06T16:20:57.000Z",
        "assignmentType": "GROUP",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/groups/00g1ousb3XCr9Dkr20g4"
            }
        }
    },
    {
        "id": "irb1q92TFAHzySt3x0g4",
        "role": "cr0Yq6IJxGIr0ouum0g3",
        "label": "UserCreatorRole",
        "type": "CUSTOM",
        "status": "ACTIVE",
        "created": "2019-02-06T16:20:57.000Z",
        "lastUpdated": "2019-02-06T16:20:57.000Z",
        "assignmentType": "USER",
        "resource-set": "iamoJDFKaJxGIr0oamd9g",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u1gytb3XCr9Dkr18r2"
            },
            "resource-set": {
                "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
            },
            "member": {
                "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3/members/irb1qe6PGuMc7Oh8N0g4"
            },
            "role": {
              "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
            },
            "permissions": {
                "href": "https://{yourOktaDomain}/api/v1/iam/permission-sets/cr0Yq6IJxGIr0ouum0g3/permissions"
            }
        }
    },
    {
        "id": "irb5e92YgBazyyQ3x1q5",
        "role": "cr0Yq6IJxGIr0ouum0g3",
        "label": "UserCreatorRole",
        "type": "CUSTOM",
        "status": "ACTIVE",
        "created": "2019-02-06T16:20:57.000Z",
        "lastUpdated": "2019-02-06T16:20:57.000Z",
        "assignmentType": "GROUP",
        "resource-set": "iamoakjsdQaJxGIr03int1o",
        "_links": {
          "assignee": {
            "href": "https://{yourOktaDomain}/api/v1/groups/00g1ousb3XCr9Dkr20g4"
          },
          "resource-set": {
            "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoakjsdQaJxGIr03int1o"
          },
          "member": {
            "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3/members/irb1qe6PGuMc7Oh8N0g4"
          },
          "role": {
            "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
          },
          "permissions": {
            "href": "https://{yourOktaDomain}/api/v1/iam/permission-sets/cr0Yq6IJxGIr0ouum0g3/permissions"
          }
        }
    }
]
Response example with IAM-based Standard Role
[
    {
        "id": "IFIFAX2BIRGUSTQ",
        "label": "Application Administrator",
        "type": "APP_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-06T16:17:40.000Z",
        "lastUpdated": "2019-02-06T16:17:40.000Z",
        "assignmentType": "USER",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
            }
        }
    },
  {
    "id": "irb1q92TFAHzySt3x0g4",
    "role": "cr0Yq6IJxGIr0ouum0g3",
    "label": "UserCreatorRole",
    "type": "CUSTOM",
    "status": "ACTIVE",
    "created": "2019-02-06T16:20:57.000Z",
    "lastUpdated": "2019-02-06T16:20:57.000Z",
    "assignmentType": "USER",
    "resource-set": "iamoJDFKaJxGIr0oamd9g",
    "_links": {
      "assignee": {
        "href": "https://{yourOktaDomain}/api/v1/users/00u1gytb3XCr9Dkr18r2"
      },
      "resource-set": {
        "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
      },
      "member": {
        "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3/members/irb1qe6PGuMc7Oh8N0g4"
      },
      "role": {
        "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
      },
      "permissions": {
        "href": "https://{yourOktaDomain}/api/v1/iam/permission-sets/cr0Yq6IJxGIr0ouum0g3/permissions"
      }
    }
  }, {
    "id": "irb5e92YgBazyyQ3x1q5",
    "role": "ACCESS_CERTIFICATIONS_ADMIN",
    "label": "Access Certifications Administrator",
    "type": "ACCESS_CERTIFICATIONS_ADMIN",
    "status": "ACTIVE",
    "created": "2019-02-06T16:20:57.000Z",
    "lastUpdated": "2019-02-06T16:20:57.000Z",
    "assignmentType": "USER",
    "resource-set": "ACCESS_CERTIFICATIONS_IAM_POLICY",
    "_links": {
      "assignee": {
        "href": "https://{yourOktaDomain}/api/v1/users/00u1gytb3XCr9Dkr18r2"
      },
      "resource-set": {
        "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/ACCESS_CERTIFICATIONS_IAM_POLICY"
      },
      "member": {
        "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/ACCESS_CERTIFICATIONS_IAM_POLICY/bindings/ACCESS_CERTIFICATIONS_ADMIN/members/irb1qe6PGuMc7Oh8N0g4"
      },
      "role": {
        "href": "https://{yourOktaDomain}/api/v1/iam/roles/ACCESS_CERTIFICATIONS_ADMIN"
      },
      "permissions": {
        "href": "https://{yourOktaDomain}/api/v1/iam/permission-sets/OKTA_IAM_TEST_DELIVERED_ROLE/permissions"
      }
    }
  }
]

List Roles assigned to a Group

GET /api/v1/groups/${groupId}/roles

Lists all Roles assigned to a Group

Request parameters
Parameter Description Param Type DataType Required
groupId ID of a Group URL String TRUE
Response parameters

Array of Roles

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles"
Response example
[
    {
        "id": "IFIFAX2BIRGUSTQ",
        "label": "Application Administrator",
        "type": "APP_ADMIN",
        "status": "ACTIVE",
        "created": "2019-02-27T14:48:59.000Z",
        "lastUpdated": "2019-02-27T14:48:59.000Z",
        "assignmentType": "GROUP",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3"
            }
        }
    }
]

List Roles assigned to a Client Application

GET /oauth2/v1/clients/${clientId}/roles

Lists all Roles assigned to an Client Application

Request parameters
Parameter Description Param Type DataType Required
clientId ID of a Client Application URL String TRUE
Response parameters

Array of Roles

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles"
Response example
[
    {
        "id": "JBCUYUC7IRCVGS27IFCE2SKO",
        "label": "Help Desk Administrator",
        "type": "HELP_DESK_ADMIN",
        "status": "ACTIVE",
        "created": "2023-05-01T14:24:54.000Z",
        "lastUpdated": "2023-05-01T14:24:54.000Z",
        "assignmentType": "CLIENT",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4"
            }
        }
    },
    {
        "id": "irb4ey26fpFI3vQ8y0g7",
        "label": "view_minimal",
        "type": "CUSTOM",
        "status": "ACTIVE",
        "created": "2023-05-01T15:16:47.000Z",
        "lastUpdated": "2023-05-01T15:16:47.000Z",
        "assignmentType": "CLIENT",
        "resource-set": "iam4cxy6z7hhaZCSk0g7",
        "role": "cr04cxy6yzSCtNciD0g7",
        "_links": {
            "role": {
              "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr04cxy6yzSCtNciD0g7"
            },
            "resource-set": {
              "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iam4cxy6z7hhaZCSk0g7"
            },
            "permissions": {
              "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr04cxy6yzSCtNciD0g7/permissions"
            },
            "member": {
              "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iam4cxy6z7hhaZCSk0g7/bindings/cr04cxy6yzSCtNciD0g7/members/irb4ey26fpFI3vQ8y0g7"
            },
            "assignee": {
              "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oa4ee9vgbIuqTUvd0g7"
            }
        }
    }
]

Assign a Role

Assign a Role to a User

POST /api/v1/users/${userId}/roles

Assigns a Role to a User

Request parameters
Parameter Description Param Type DataType Required
type Type of Role to assign Body Role Type TRUE
userId ID of a User URL String TRUE
Response parameters

The assigned Role

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "type": "SUPER_ADMIN"
}' "https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles"
Response example
{
  "id": "ra1b8anIk7rx7em7L0g4",
  "label": "Super Organization Administrator",
  "type": "SUPER_ADMIN",
  "status": "ACTIVE",
  "created": "2015-09-06T15:28:47.000Z",
  "lastUpdated": "2015-09-06T15:28:47.000Z"
}

Assign a Role to a Group

POST /api/v1/groups/${groupId}/roles

Assigns a Role to a Group

Request parameters
Parameter Description Param Type DataType Required
groupId ID of a Group URL String TRUE
type Type of Role to assign Body Role Type TRUE
Response parameters

The assigned Role

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "type": "ORG_ADMIN"
}' "https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles"
Response example
{
    "id": "grasraHPx7i79ajaJ0g3",
    "label": "Organization Administrator",
    "type": "ORG_ADMIN",
    "status": "ACTIVE",
    "created": "2019-02-27T14:56:55.000Z",
    "lastUpdated": "2019-02-27T14:56:55.000Z",
    "assignmentType": "GROUP",
    "_links": {
        "assignee": {
            "href": "https://{yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3"
        }
    }
}

Assign a Role to a Client Application

POST /oauth2/v1/clients/${clientId}/roles

Assigns a Role to a Client

Request parameters
Parameter Description Param Type DataType Required
clientId ID of a Client Application URL String TRUE
type Type of Role to assign Body Role Type TRUE
Response parameters

The assigned Role

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "type": "HELP_DESK_ADMIN"
}' "https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles"
Response example
{ 
    "id": "JBCUYUC7IRCVGS27IFCE2SKO",
    "label": "Help Desk Administrator",
    "type": "HELP_DESK_ADMIN",
    "status": "ACTIVE",
    "created": "2023-05-01T14:24:54.000Z",
    "lastUpdated": "2023-05-01T14:24:54.000Z",
    "assignmentType": "CLIENT",
    "_links": {
        "assignee": {
            "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4"
        }
    }
}

Assign a Custom Role to a User, Group or Client Application

The recommended way to assign a Custom Role is by using one of the Custom Role assignment operations. However, you can also assign a Custom Role using the following method:

POST /api/v1/users/${userId}/roles

Or to assign to a Group:

POST /api/v1/groups/${groupId}/roles

Or to assign to a Client Application:

POST /oauth2/v1/clients/${clientId}/roles

as long as the request body contains a Custom role ID and a resource-set ID. Also, type must be CUSTOM.

Request parameters
Parameter Description Param Type DataType Required
userId, groupId, clientId User ID, Group ID, or Client ID URL String TRUE
type Type of Role to assign Body String literal: CUSTOM TRUE
role ID of the Custom Role Body String TRUE
resource-set ID of the Resource Set Body String TRUE
Response parameters

The assigned Role

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "type": "CUSTOM",
      "role": "cr0Yq6IJxGIr0ouum0g3",
      "resource-set": "iamoJDFKaJxGIr0oamd9g"
}' "https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles"
Response example
{
  "id": "irb1q92TFAHzySt3x0g4",
  "role": "cr0WxyzJxGIr0ouum0g4",
  "label": "UserCreatorRole",
  "type": "CUSTOM",
  "status": "ACTIVE",
  "created": "2019-02-06T16:20:57.000Z",
  "lastUpdated": "2019-02-06T16:20:57.000Z",
  "assignmentType": "GROUP",
  "resource-set": "iamoJDFKaJxGIr0oamd9g",
  "_links": {
    "assignee": {
      "href": "https://{yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
    },
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    },
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions"
    }
  }
}

Assign an IAM-based Standard Role to a User or Group or Client Application

You can assign an IAM-based Standard Role like any other Standard Role using the appropriate url for the Principal.

Request example for Group
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "type": "ACCESS_REQUESTS_ADMIN"
}' "https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles"
Response example
{
  "id": "irb1q92TFAHzySt3x0g4",
  "role": "ACCESS_REQUESTS_ADMIN",
  "label": "Access Requests Administrator",
  "type": "ACCESS_REQUESTS_ADMIN",
  "status": "ACTIVE",
  "created": "2019-02-06T16:20:57.000Z",
  "lastUpdated": "2019-02-06T16:20:57.000Z",
  "assignmentType": "GROUP",
  "resource-set": "ACCESS_CERTIFICATIONS_IAM_POLICY",
  "_links": {
    "assignee": {
      "href": "https://{yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/ACCESS_CERTIFICATIONS_IAM_POLICY"
    },
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/ACCESS_REQUESTS_ADMIN"
    },
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/ACCESS_REQUESTS_ADMIN/permissions"
    },
    "member": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/ACCESS_CERTIFICATIONS_IAM_POLICY/bindings/ACCESS_REQUESTS_ADMIN/members/irb4jlomnnDBuBDyJ0g7"
    },
  }
}
Request example for Client Application
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
      "type": "ACCESS_REQUESTS_ADMIN"
}' "https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles"
Response example
{
  "id": "irb4jlodtdN4yJ88b0g7",
  "role": "ACCESS_REQUESTS_ADMIN",
  "label": "Access Requests Administrator",
  "type": "ACCESS_REQUESTS_ADMIN",
  "status": "ACTIVE",
  "created": "2023-07-06T21:52:48.000Z",
  "lastUpdated": "2023-07-06T21:52:48.000Z",
  "assignmentType": "CLIENT",
  "resource-set": "ACCESS_CERTIFICATIONS_IAM_POLICY",
  "_links": {
    "assignee": {
      "href": "https://{yourOktaDomain}/api/v1/groups/0oa5vymVNCe2cPEeZ0g4"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/ACCESS_CERTIFICATIONS_IAM_POLICY"
    },
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/ACCESS_REQUESTS_ADMIN"
    },
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/ACCESS_REQUESTS_ADMIN/permissions"
    },
    "member": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/ACCESS_CERTIFICATIONS_IAM_POLICY/bindings/ACCESS_REQUESTS_ADMIN/members/irb4jlodtdN4yJ88b0g7"
    },
  }
}

Unassign a Role

Unassign a Role from a User

DELETE /api/v1/users/${userId}/roles/${roleId}

Unassigns a Role from a User

Request parameters
Parameter Description Param Type DataType Required
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/ra1b8anIk7rx7em7L0g4"
Response example
HTTP/1.1 204 No Content

Unassign a Role from a Group

DELETE /api/v1/groups/${groupId}/roles/${roleId}

Unassigns a Role from a Group

Request parameters
Parameter Description Param Type DataType Required
groupId ID of a Group URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/grasraHPx7i79ajaJ0g3"
Response example
HTTP/1.1 204 No Content

Unassign a Role from a Client Application

DELETE /oauth2/v1/clients/${clientId}/roles/${roleId}

Unassigns a Role from a Client Application

Request parameters
Parameter Description Param Type DataType Required
clientId ID of a Client Application URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/JBCUYUC7IRCVGS27IFCE2SKO"
Response example
HTTP/1.1 204 No Content

Unassign a Custom Role from a User or Group or Client Application

The recommended way to unassign a Custom Role is by using one of the Custom Role assignment operations. However, you can also unassign a Custom Role by using the following method:

DELETE /api/v1/users/${userId}/roles/${bindingId}

Or to unassign from a Group:

DELETE /api/v1/groups/${groupId}/roles/${bindingId}

Or to unassign from a Client Application:

DELETE /oauth2/v1/clients/${clientId}/roles/${bindingId}

but note that instead of ${roleId}, you must provide a ${bindingId}.

Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/irb1q92TFAHzySt3x0g4"
Response example
HTTP/1.1 204 No Content

Role target operations

Role targets are a way of defining permissions for admin roles into a smaller subset of Groups or Apps within your org. Targets limit an admin's permissions to a targeted area of the org. You can define admin roles to target Groups, Applications, and Application Instances.

  • Group targets: Grant an admin permission to manage only a specified Group. For example, an admin role may be assigned to manage only the IT Group.
  • App targets: Grant an admin permission to manage all instances of the specified Apps. Target Apps are Okta catalog Apps. For example, you can have multiple configurations of an Okta catalog App, such as Salesforce or Facebook. When you add a Salesforce or Facebook App as a target, the admin receives permission to manage all the instances of those Apps and create instances of them.
  • App Instance targets: Grant an admin permission to manage an instance of one App or instances of multiple Apps. App Instances are specific Apps that admins have created in their org. For example, there may be a Salesforce App configured differently for each sales region of a company. When you create an App Instance target, you can assign an admin to manage only two instances of the configured Salesforce Apps and then also to manage an instance of another configured App such as Workday.

Note: Don't use these operations with a Custom Role ID. Custom Role assignments always require a target Resource Set. Use Custom Role assignment operations or the backward-compatible Role assignment or unassignment operations.

Group administrator role group targets

Assigns a group admin role to a specific Group that grants the admin permission to manage only that Group. For example, you can assign an admin role to manage only the IT group. The permissions for specifically what an admin can do within that Group depends on the admin role that they're assigned to. See Administrators (opens new window).

List Group targets for the group administrator role

List Group targets for the group administrator role given to a user

GET /api/v1/users/${userId}/roles/${roleId}/targets/groups

Lists all Group targets for a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a User

Request parameters
Parameter Description Param Type DataType Required
after Specifies the pagination cursor for the next page of targets Query String FALSE
limit Specifies the number of results for a page (default is 20) Query Number FALSE
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE

Treat the page cursor as an opaque value. You can obtain it through the next link relation. See Pagination.

Response parameters

Array of Groups

If the Role isn't scoped to specific Group targets, an empty array [] is returned.

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/groups"
Response example
[
  {
    "id": "00g1emaKYZTWRYYRRTSK",
    "objectClass": [
      "okta:user_group"
    ],
    "profile": {
      "name": "West Coast Users",
      "description": "All Users West of The Rockies"
    },
    "_links": {
      "logo": [
        {
          "href": "https://{yourOktaDomain}/img/logos/groups/okta-medium.png",
          "name": "medium",
          "type": "image/png"
        },
        {
          "href": "https://{yourOktaDomain}/img/logos/groups/okta-large.png",
          "name": "large",
          "type": "image/png"
        }
      ],
      "users": {
        "href": "https://{yourOktaDomain}/api/v1/groups/00g1emaKYZTWRYYRRTSK/users"
      },
      "apps": {
        "href": "https://{yourOktaDomain}/api/v1/groups/00g1emaKYZTWRYYRRTSK/apps"
      }
    }
  }
]
List Group targets for a group administrator role given to a group

GET /api/v1/groups/${groupId}/roles/${roleId}/targets/groups

Lists all Group targets for a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a Group

Request parameters
Parameter Description Param Type DataType Required
after Specifies the pagination cursor for the next page of targets Query String FALSE
groupId ID of a Group URL String TRUE
limit Specifies the number of results for a page (default is 20) Query Number FALSE
roleId ID of a Role URL String TRUE

Treat the page cursor as an opaque value. You can obtain it through the next link relation. See Pagination.

Response parameters

Array of Groups

If the Role isn't scoped to specific Group targets, an empty array [] is returned.

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/JBCUYUC7IRCVGS27IFCE2SKO/targets/groups"
Response example
[
    {
        "id": "00gsrc96agspOaiP40g3",
        "created": "2019-02-27T15:19:11.000Z",
        "lastUpdated": "2019-02-27T15:19:11.000Z",
        "lastMembershipUpdated": "2019-02-27T15:19:11.000Z",
        "objectClass": [
            "okta:user_group"
        ],
        "type": "OKTA_GROUP",
        "profile": {
            "name": "userGroup0",
            "description": null
        },
        "_links": {
            "logo": [
                {
                    "name": "medium",
                    "href": "https://{yourOktaDomain}/assets/img/logos/groups/okta-medium.d7fb831bc4e7e1a5d8bd35dfaf405d9e.png",
                    "type": "image/png"
                },
                {
                    "name": "large",
                    "href": "https://{yourOktaDomain}/assets/img/logos/groups/okta-large.511fcb0de9da185b52589cb14d581c2c.png",
                    "type": "image/png"
                }
            ],
            "users": {
                "href": "https://{yourOktaDomain}/api/v1/groups/00gsrc96agspOaiP40g3/users"
            },
            "apps": {
                "href": "https://{yourOktaDomain}/api/v1/groups/00gsrc96agspOaiP40g3/apps"
            }
        }
    }
]
List Group targets for a group administrator role given to a client application

GET /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/groups

Lists all Group targets for a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a Client Application

Request parameters
Parameter Description Param Type DataType Required
after Specifies the pagination cursor for the next page of targets Query String FALSE
clientId ID of a Client Application URL String TRUE
limit Specifies the number of results for a page (default is 20) Query Number FALSE
roleId ID of a Role URL String TRUE

Treat the page cursor as an opaque value. You can obtain it through the next link relation. See Pagination.

Response parameters

Array of Groups

If the Role isn't scoped to specific Group targets, an empty array [] is returned.

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/JBCUYUC7IRCVGS27IFCE2SKO/targets/groups"
Response example
[
    {
        "id": "00gsrc96agspOaiP40g3",
        "created": "2019-02-27T15:19:11.000Z",
        "lastUpdated": "2019-02-27T15:19:11.000Z",
        "lastMembershipUpdated": "2019-02-27T15:19:11.000Z",
        "objectClass": [
            "okta:user_group"
        ],
        "type": "OKTA_GROUP",
        "profile": {
            "name": "userGroup0",
            "description": null
        },
        "_links": {
            "logo": [
                {
                    "name": "medium",
                    "href": "https://{yourOktaDomain}/assets/img/logos/groups/okta-medium.d7fb831bc4e7e1a5d8bd35dfaf405d9e.png",
                    "type": "image/png"
                },
                {
                    "name": "large",
                    "href": "https://{yourOktaDomain}/assets/img/logos/groups/okta-large.511fcb0de9da185b52589cb14d581c2c.png",
                    "type": "image/png"
                }
            ],
            "users": {
                "href": "https://{yourOktaDomain}/api/v1/groups/00gsrc96agspOaiP40g3/users"
            },
            "apps": {
                "href": "https://{yourOktaDomain}/api/v1/groups/00gsrc96agspOaiP40g3/apps"
            }
        }
    }
]

Assign a Group target to a group administrator Role

Assign a Group target to a group administrator Role given to a User

PUT /api/v1/users/${userId}/roles/${roleId}/targets/groups/${groupId}

Assigns a Group target to a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a User

When you assign the first Group target, you reduce the scope of the role assignment. The Role no longer applies to all targets but applies only to the specified target.

Request parameters
Parameter Description Param Type DataType Required
groupId ID of the Group target to scope role assignment URL String TRUE
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/groups/00garkxjAHDYPFcsP0g4"
Response example
HTTP/1.1 204 No Content
Assign a Group target to a group administrator Role given to a Group

PUT /api/v1/groups/${groupId}/roles/${roleId}/targets/groups/${targetGroupId}

Assigns a Group target to a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a Group

When you assign the first Group target, you reduce the scope of the role assignment. The Role no longer applies to all targets but applies only to the specified target.

Request parameters
Parameter Description Param Type DataType Required
groupId ID of an admin Group URL String TRUE
roleId ID of a Role URL String TRUE
targetGroupId ID of the Group target to scope role assignment URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/JBCUYUC7IRCVGS27IFCE2SKO/targets/groups/00gsrhsUaRoUib0XQ0g3"
Response example
HTTP/1.1 204 No Content
Assign a Group target to a group administrator Role given to a Client Application

PUT /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/groups/${targetGroupId}

Assigns a Group target to a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a Client Application

When you assign the first Group target, you reduce the scope of the role assignment. The Role no longer applies to all targets but applies only to the specified target.

Request parameters
Parameter Description Param Type DataType Required
clientId ID of an Client Application URL String TRUE
roleId ID of a Role URL String TRUE
targetGroupId ID of the Group target to scope role assignment URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/JBCUYUC7IRCVGS27IFCE2SKO/targets/groups/00gsrhsUaRoUib0XQ0g3"
Response example
HTTP/1.1 204 No Content

Remove a Group target from a group administrator role

Remove a Group target from a group administrator role given to a user

DELETE /api/v1/users/${userId}/roles/${roleId}/targets/groups/${groupId}

Removes a Group target from a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a User

Note: Don't remove the last Group target from a role assignment, as it causes an exception. If you need a role assignment that applies to all Groups, the API consumer should delete the USER_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
groupId ID of the Group target for role assignment URL String TRUE
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/groups/00garkxjAHDYPFcsP0g4"
Response example
HTTP/1.1 204 No Content
Remove a Group target from a group administrator role given to a group

DELETE /api/v1/groups/${groupId}/roles/${roleId}/targets/groups/${targetGroupId}

Removes a Group target from a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a Group

Note: Don't remove the last Group target from a role assignment, as it causes an exception. If you need a role assignment that applies to all Groups, the API consumer should delete the USER_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
groupId ID of an admin Group URL String TRUE
roleId ID of a Role URL String TRUE
targetGroupId ID of the Group target for role assignment URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/JBCUYUC7IRCVGS27IFCE2SKO/targets/groups/00gsrhsUaRoUib0XQ0g3"
Response example
HTTP/1.1 204 No Content
Remove a Group target from a group administrator role given to a Client Application

DELETE /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/groups/${targetGroupId}

Removes a Group target from a USER_ADMIN or HELP_DESK_ADMIN Role assigned to a Client Application

Note: Don't remove the last Group target from a role assignment, as it causes an exception. If you need a role assignment that applies to all Groups, the API consumer should delete the USER_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
clientId ID of an Client Application URL String TRUE
roleId ID of a Role URL String TRUE
targetGroupId ID of the Group target for role assignment URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/JBCUYUC7IRCVGS27IFCE2SKO/targets/groups/00gsrhsUaRoUib0XQ0g3"
Response example
HTTP/1.1 204 No Content

App administrator role for App targets

Assign an admin role to a subset of Apps to grant the admin permission to manage all the instances of those Apps. Targeted Apps are Okta catalog Apps, and you can assign App targets for these Apps to an admin role regardless of whether a specific instance of the App has been created. For example, there can be multiple configurations of one Okta catalog App, such as Salesforce or Facebook. When you add a Salesforce or Facebook App as a target, that grants the admin permission to manage all the instances of Salesforce or Facebook Apps and create instances of them.

List App targets for an App administrator role

List App targets for an App administrator role given to a User

GET /api/v1/users/${userId}/roles/${roleId}/targets/catalog/apps

Lists all the App targets for an APP_ADMIN Role assigned to a User

Request parameters
Parameter Description Param Type DataType Required
after Specifies the pagination cursor for the next page of targets Query String FALSE
limit Specifies the number of results for a page (default is 20) Query Number FALSE
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE

Treat the page cursor as an opaque value. You can obtain it through the next link relation. See Pagination.

Response parameters

Array of catalog Apps

If the Role isn't scoped to specific Apps in the catalog, an empty array [] is returned.

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/catalog/apps"
Response example

The example shows two applications and two instances. The response for instances has an id field.

[
  {
    "name": "salesforce",
    "displayName": "Salesforce.com",
    "description": "Salesforce",
    "status": "ACTIVE",
    "lastUpdated": "2014-06-03T16:17:13.000Z",
    "category": "CRM",
    "verificationStatus": "OKTA_VERIFIED",
    "website": "http://www.salesforce.com",
    "signOnModes": [
      "SAML_2_0"
    ],
    "features": [
      "IMPORT_NEW_USERS",
      "IMPORT_PROFILE_UPDATES",
      "IMPORT_USER_SCHEMA",
      "PUSH_NEW_USERS",
      "PUSH_PASSWORD_UPDATES",
      "PUSH_PROFILE_UPDATES",
      "PUSH_USER_DEACTIVATION",
      "REACTIVATE_USERS"
    ],
    "_links": {
      "logo": [
        {
          "name": "medium",
          "href": "https://{yourOktaDomain}/img/logos/salesforce_logo.png",
          "type": "image/png"
        }
      ],
      "self": {
          "href": "https://{yourOktaDomain}/api/v1/catalog/apps/salesforce"
      }
    }
  },
  {
    "name": "boxnet",
    "displayName": "Box",
    "description": "Cloud storage.",
    "status": "ACTIVE",
    "lastUpdated": "2014-06-03T16:17:13.000Z",
    "category": "CM",
    "verificationStatus": "OKTA_VERIFIED",
    "website": "http://www.box.net",
    "signOnModes": [
      "SAML_2_0"
    ],
    "features": [
      "GROUP_PUSH",
      "IMPORT_NEW_USERS",
      "IMPORT_PROFILE_UPDATES",
      "PUSH_NEW_USERS",
      "PUSH_PROFILE_UPDATES",
      "PUSH_USER_DEACTIVATION",
      "REACTIVATE_USERS"
    ],
    "_links": {
      "logo": [
        {
          "name": "medium",
          "href": "https://{yourOktaDomain}/img/logos/box.png",
          "type": "image/png"
        }
      ],
      "self": {
          "href": "https://{yourOktaDomain}/api/v1/catalog/apps/boxnet"
      }
    }
  },
  {
    "name": "Facebook for Detroit Office",
    "status": "ACTIVE",
    "id": "0oapsqQ5dv19pqyEo0g3",
    "_links": {
      "self": {
          "href": "https://{yourOktaDomain}/api/v1/apps/0oapsqQ5dv19pqyEo0g3"
      }
    }
  },
  {
    "name": "Facebook (Toronto)",
    "status": "ACTIVE",
    "id": "0obdfgrQ5dv29pqyQo0f5",
    "_links": {
       "self": {
           "href": "https://{yourOktaDomain}/api/v1/apps/0obdfgrQ5dv29pqyQo0f5"
       }
    }
  }
]
List App targets for App administrator role given to a Group

GET /api/v1/groups/${groupId}/roles/${roleId}/targets/catalog/apps

Lists all the App targets for an APP_ADMIN Role assigned to a Group

Request Parameters
Parameter Description Param Type DataType Required
after Specifies the pagination cursor for the next page of targets Query String FALSE
groupId ID of a Group URL String TRUE
limit Specifies the number of results for a page (default is 20) Query Number FALSE
roleId ID of a Role URL String TRUE

Treat the page cursor as an opaque value. You can obtain it through the next link relation. See Pagination.

Response parameters

Array of catalog Apps

If the Role isn't scoped to specific Apps in the catalog, an empty array [] is returned.

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps"
Response example

The example shows one application and one instance. The response for instances has an id field.

[
    {
        "name": "facebook",
        "displayName": "Facebook",
        "description": "Giving people the power to share and make the world more open and connected.",
        "status": "ACTIVE",
        "lastUpdated": "2017-07-19T23:37:37.000Z",
        "category": "SOCIAL",
        "verificationStatus": "OKTA_VERIFIED",
        "website": "http://www.facebook.com/",
        "signOnModes": [
            "BROWSER_PLUGIN"
        ],
        "_links": {
            "logo": [
                {
                    "name": "medium",
                    "href": "https://{yourOktaDomain}/assets/img/logos/facebook.e8215796628b5eaf687ba414ae245659.png",
                    "type": "image/png"
                }
            ],
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/catalog/apps/facebook"
            }
        }
    },
    {
        "name": "24 Seven Office 0",
        "status": "ACTIVE",
        "id": "0oasrudLtMlzAsTxk0g3",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/apps/0oasrudLtMlzAsTxk0g3"
            }
        }
    }
]
List App targets for App administrator role given to a Client Application

GET /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/catalog/apps

Lists all the App targets for an APP_ADMIN Role assigned to a Client Application

Request Parameters
Parameter Description Param Type DataType Required
after Specifies the pagination cursor for the next page of targets Query String FALSE
clientId ID of a Client Application URL String TRUE
limit Specifies the number of results for a page (default is 20) Query Number FALSE
roleId ID of a Role URL String TRUE

Treat the page cursor as an opaque value. You can obtain it through the next link relation. See Pagination.

Response parameters

Array of catalog Apps

If the Role isn't scoped to specific Apps in the catalog, an empty array [] is returned.

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps"
Response example

The example shows one application and one instance. The response for instances has an id field.

[
    {
        "name": "facebook",
        "displayName": "Facebook",
        "description": "Giving people the power to share and make the world more open and connected.",
        "status": "ACTIVE",
        "lastUpdated": "2017-07-19T23:37:37.000Z",
        "category": "SOCIAL",
        "verificationStatus": "OKTA_VERIFIED",
        "website": "http://www.facebook.com/",
        "signOnModes": [
            "BROWSER_PLUGIN"
        ],
        "_links": {
            "logo": [
                {
                    "name": "medium",
                    "href": "https://{yourOktaDomain}/assets/img/logos/facebook.e8215796628b5eaf687ba414ae245659.png",
                    "type": "image/png"
                }
            ],
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/catalog/apps/facebook"
            }
        }
    },
    {
        "name": "24 Seven Office 0",
        "status": "ACTIVE",
        "id": "0oasrudLtMlzAsTxk0g3",
        "_links": {
            "self": {
                "href": "https://{yourOktaDomain}/api/v1/apps/0oasrudLtMlzAsTxk0g3"
            }
        }
    }
]

Assign an App target to an App administrator Role

Assign an App target to an App administrator Role given to a User

PUT /api/v1/users/${userId}/roles/${roleId}/targets/catalog/apps/${appName}

Assigns an App target for an APP_ADMIN Role assigned to a User

When you assign the first App target, you reduce the scope of the Role assignment. The Role no longer applies to all App targets, but applies only to the specified target.

Assigning an App target overrides any existing App Instance targets of the App. For example, if someone was assigned to administer a specific Facebook instance, calling this endpoint with facebook for appName, would make them administrator for all Facebook instances.

Request parameters
Parameter Description Param Type DataType Required
appName Name of the App target from the catalog to scope Role assignment URL String TRUE
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/catalog/apps/amazon_aws"
Response example
HTTP/1.1 204 No Content
Assign an App target to an App administrator Role given to a Group

PUT /api/v1/groups/${groupId}/roles/${roleId}/targets/catalog/apps/${appName}

Assigns an App target to an APP_ADMIN Role assigned to a Group

When you assign the first App target, you reduce the scope of the role assignment. The Role no longer applies to all App targets but applies only to the specified target.

An App target that is assigned overrides any existing instance targets of the app. For example, if someone is assigned to administer a specific Facebook instance, a call to this endpoint with facebook for appName would make that person the administrator for all Facebook instances.

Request parameters
Parameter Description Param Type DataType Required
groupId ID of a Group URL String TRUE
roleId ID of a Role URL String TRUE
appName Name of the App target from the catalog to scope role assignment URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/amazon_aws"
Response example
HTTP/1.1 204 No Content
Assign an App target to an App administrator Role given to a Client Application

PUT /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/catalog/apps/${appName}

Assigns an App target to an APP_ADMIN Role assigned to a Client Application

When you assign the first App target, you reduce the scope of the role assignment. The Role no longer applies to all App targets but applies only to the specified target.

An App target that is assigned overrides any existing instance targets of the app. For example, if someone is assigned to administer a specific Facebook instance, a call to this endpoint with facebook for appName would make that person the administrator for all Facebook instances.

Request parameters
Parameter Description Param Type DataType Required
clientId ID of a Client Application URL String TRUE
roleId ID of a Role URL String TRUE
appName Name of the App target from the catalog to scope role assignment URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/amazon_aws"
Response example
HTTP/1.1 204 No Content

Assign an App Instance target to an App administrator Role

Assign an admin role to a specific App Instance to grant the admin permission to manage an instance of one App or instances of multiple Apps. App Instances are specific Apps that admins create in their org. For example, there may be a Salesforce App configured differently for each sales region of a company. When you create an App Instance target, you may assign an admin to manage only two instances of the configured Salesforce Apps and then also to manage an instance of another configured App such as Workday.

Note: You can target a mixture of both App and App Instance targets, but can't assign permissions to manage all the instances of an App and then a subset of that same App. For example, you can't specify that an admin has access to manage all the instances of a Salesforce app and then also specific configurations of the Salesforce app.

Assign an App Instance target to an App administrator Role given to a User

PUT /api/v1/users/${userId}/roles/${roleId}/targets/catalog/apps/${appName}/${appInstanceId}

Assigns an App Instance target to an APP_ADMIN Role assigned to a User

When you assign the first App or App Instance target, you reduce the scope of the role assignment. The Role no longer applies to all App targets, but applies only to the specified target.

Note: You can target a mixture of both App and App Instance targets, but can't assign permissions to manage all the instances of an App and then a subset of that same App. For example, you can't specify that an admin has access to manage all the instances of a Salesforce app and then also specific configurations of the Salesforce app.

Request parameters
Parameter Description Param Type DataType Required
userId ID of a User URL String TRUE
roleId ID of a Role URL String TRUE
appName Name of the App target from the catalog to scope role assignment URL String TRUE
appInstanceId ID of the App Instance target to scope role assignment URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/catalog/apps/amazon_aws/0oasrudLtMlzAsTxk0g3"
Response example
HTTP/1.1 204 No Content
Assign an App Instance target to an App administrator Role given to a Group

PUT /api/v1/groups/${groupId}/roles/${roleId}/targets/catalog/apps/${appName}/${appInstanceId}

Assigns an App Instance target to an APP_ADMIN Role assigned to a Group

When you assign the first App or App Instance target, you reduce the scope of the role assignment. The Role no longer applies to all App targets, but applies only to the specified target.

Note: You can target a mixture of both App and App Instance targets, but can't assign permissions to manage all the instances of an App and then a subset of that same App. For example, you can't specify that an admin has access to manage all the instances of a Salesforce app and then also specific configurations of the Salesforce app.

Request parameters
Parameter Description Param Type DataType Required
appInstanceId ID of the App Instance target to scope role assignment URL String TRUE
appName Name of the App target from the catalog to scope role assignment URL String TRUE
groupId ID of a Group URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/facebook/0oassqD8YkfwsJeV60g3"
Response example
HTTP/1.1 204 No Content
Assign an App Instance target to an App administrator Role given to a Client Application

PUT /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/catalog/apps/${appName}/${appInstanceId}

Assigns an App Instance target to an APP_ADMIN Role assigned to a Client Application

When you assign the first App or App Instance target, you reduce the scope of the role assignment. The Role no longer applies to all App targets, but applies only to the specified target.

Note: You can target a mixture of both App and App Instance targets, but can't assign permissions to manage all the instances of an App and then a subset of that same App. For example, you can't specify that an admin has access to manage all the instances of a Salesforce app and then also specific configurations of the Salesforce app.

Request parameters
Parameter Description Param Type DataType Required
appInstanceId ID of the App Instance target to scope role assignment URL String TRUE
appName Name of the App target from the catalog to scope role assignment URL String TRUE
clientId ID of a Client Application URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/facebook/0oassqD8YkfwsJeV60g3"
Response example
HTTP/1.1 204 No Content

Remove an App target from an App administrator role

Remove an App target from an App administrator role given to a User

DELETE /api/v1/users/${userId}/roles/${roleId}/targets/catalog/apps/${appName}

Removes an App target from an APP_ADMIN Role assigned to a User

Note: Don't remove the last App target from a role assignment, as it causes an exception. If you need a role assignment that applies to all the Apps, the API consumer should delete the APP_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
appName Name of the App target for role assignment URL String TRUE
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/catalog/apps/amazon_aws"
Response example
HTTP/1.1 204 No Content
Remove an App target from an App administrator role given to a Group

DELETE /api/v1/groups/${groupId}/roles/${roleId}/targets/catalog/apps/${appName}

Removes an App target from an APP_ADMIN Role assigned to a Group

Note: Don't remove the last App target from a role assignment, as it causes an exception. If you need a role assignment that applies to all the Apps, the API consumer should delete the APP_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
appName Name of the App target for role assignment URL String TRUE
groupId ID of a Group URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/facebook"
Response example
HTTP/1.1 204 No Content
Remove an App target from an App administrator role given to a Client Application

DELETE /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/catalog/apps/${appName}

Removes an App target from an APP_ADMIN Role assigned to a Client Application

Note: Don't remove the last App target from a role assignment, as it causes an exception. If you need a role assignment that applies to all the Apps, the API consumer should delete the APP_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
appName Name of the App target for role assignment URL String TRUE
clientId ID of a Client Application URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/facebook"
Response example
HTTP/1.1 204 No Content

Remove an App instance target from an App administrator role

Remove an App instance target from an App administrator role given to a User

DELETE /api/v1/users/${userId}/roles/${roleId}/targets/catalog/apps/${appName}/${appInstanceId}

Removes an App instance target from an APP_ADMIN Role assigned to a User

Note: Don't remove the last App target from a role assignment, as it causes an exception. If you need a role assignment that applies to all the Apps, the API consumer should delete the APP_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
appInstanceId ID of the App Instance target for role assignment URL String TRUE
appName Name of App target for role assignment URL String TRUE
roleId ID of a Role URL String TRUE
userId ID of a User URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00u6fud33CXDPBXULRNG/roles/KVJUKUS7IFCE2SKO/targets/catalog/apps/amazon_aws"
Response example
HTTP/1.1 204 No Content
Remove an App instance target from an App administrator role given to a Group

DELETE /api/v1/groups/${groupId}/roles/${roleId}/targets/catalog/apps/${appName}/${appInstanceId}

Removes an App Instance target from an APP_ADMIN Role assigned to a Group

Note: Don't remove the last App target from a role assignment, as it causes an exception. If you need a role assignment that applies to all the Apps, the API consumer should delete the APP_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
appInstanceId ID of the App Instance target for role assignment URL String TRUE
appName Name of the App target for role assignment URL String TRUE
groupId ID of a Group URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/groups/00gsr2IepS8YhHRFf0g3/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/facebook/0oassqD8YkfwsJeV60g3"
Response example
HTTP/1.1 204 No Content
Remove an App instance target from an App administrator role given to a Client Application

DELETE /oauth2/v1/clients/${clientId}/roles/${roleId}/targets/catalog/apps/${appName}/${appInstanceId}

Removes an App Instance target from an APP_ADMIN Role assigned to a Client Application

Note: Don't remove the last App target from a role assignment, as it causes an exception. If you need a role assignment that applies to all the Apps, the API consumer should delete the APP_ADMIN role assignment and recreate it.

Request parameters
Parameter Description Param Type DataType Required
appInstanceId ID of the App Instance target for role assignment URL String TRUE
appName Name of the App target for role assignment URL String TRUE
clientId ID of a Client Application URL String TRUE
roleId ID of a Role URL String TRUE
Response parameters
HTTP/1.1 204 No Content
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4/roles/IFIFAX2BIRGUSTQ/targets/catalog/apps/facebook/0oassqD8YkfwsJeV60g3"
Response example
HTTP/1.1 204 No Content

Role object

Examples

Sample Role assigned to the User directly

{
    "id": "ra125eqBFpETrMwu80g4",
    "label": "Organization Administrator",
    "type": "ORG_ADMIN",
    "status": "ACTIVE",
    "created": "2019-02-06T16:17:40.000Z",
    "lastUpdated": "2019-02-06T16:17:40.000Z",
    "assignmentType": "USER",
    "_links": {
        "assignee": {
            "href": "https://{yourOktaDomain}/api/v1/users/00ur32Vg0fvpyHZeQ0g3"
        }
    }
}

Sample Role assigned to the User through a Group membership

{
    "id": "gra25fapn1prGTBKV0g4",
    "label": "API Access Management Administrator",
    "type": "API_ACCESS_MANAGEMENT_ADMIN",
    "status": "ACTIVE",
    "created": "2019-02-06T16:20:57.000Z",
    "lastUpdated": "2019-02-06T16:20:57.000Z",
    "assignmentType": "GROUP",
    "_links": {
        "assignee": {
            "href": "https://{yourOktaDomain}/api/v1/groups/00g1ousb3XCr9Dkr20g4"
        }
    }
}

Sample Custom Role assigned to the User directly

The following fields are different compared to those for an individually assigned standard Role:

  • The id field has a different format, but it has the same application.
  • The type field for Custom Roles always has the value CUSTOM.
  • The new resource-set field gives the ID of the Resource Set to which this assignment applies.
  • The _links field has three new fields:
    • resource-set is the GET link to the Resource Set to which this assignment is granted.
    • role is the GET link to the Role to which this assignment is granted.
    • permissions is the GET link to the Permissions to which this assignment is granted.
    {
        "id": "irb1q92TFAHzySt3x0g4",
        "role": "cr0Yq6IJxGIr0ouum0g3",
        "label": "UserCreatorRole",
        "type": "CUSTOM",
        "status": "ACTIVE",
        "created": "2019-02-06T16:20:57.000Z",
        "lastUpdated": "2019-02-06T16:20:57.000Z",
        "assignmentType": "USER",
        "resource-set": "iamoJDFKaJxGIr0oamd9g",
        "_links": {
            "assignee": {
                "href": "https://{yourOktaDomain}/api/v1/users/00u1gytb3XCr9Dkr18r2"
            },
            "resource-set": {
                "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g"
            },
            "member": {
                "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3/members/irb1qe6PGuMc7Oh8N0g4"
            },
            "role": {
                "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
            },
            "permissions": {
                "href": "https://{yourOktaDomain}/api/v1/iam/permission-sets/cr0Yq6IJxGIr0ouum0g3/permissions"
            }
        }
    }

Sample Custom Role assigned to the User through a Group membership

The following fields are different compared to those for a Group assigned standard Role:

  • The id field has a different format, but it has the same application.
  • The type field for Custom Roles always has the value CUSTOM.
  • The new resource-set field gives the ID of the Resource Set to which this assignment applies.
  • The _links field has three new fields:
    • resource-set is the GET link to the Resource Set to which this assignment is granted.
    • role is the GET link to the Role to which this assignment is granted.
    • permissions is the GET link to the Permissions to which this assignment is granted.
{
  "id": "irb5e92YgBazyyQ3x1q5",
  "role": "cr0Yq6IJxGIr0ouum0g3",
  "label": "UserCreatorRole",
  "type": "CUSTOM",
  "status": "ACTIVE",
  "created": "2019-02-06T16:20:57.000Z",
  "lastUpdated": "2019-02-06T16:20:57.000Z",
  "assignmentType": "GROUP",
  "resource-set": "iamoakjsdQaJxGIr03int1o",
  "_links": {
    "assignee": {
      "href": "https://{yourOktaDomain}/api/v1/groups/00g1ousb3XCr9Dkr20g4"
    },
    "resource-set": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoakjsdQaJxGIr03int1o"
    },
    "member": {
      "href": "https://{yourOktaDomain}/api/v1/iam/resource-sets/iamoJDFKaJxGIr0oamd9g/bindings/cr0Yq6IJxGIr0ouum0g3/members/irb1qe6PGuMc7Oh8N0g4"
    },
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    },
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/permission-sets/cr0Yq6IJxGIr0ouum0g3/permissions"
    }
  }
}

Role properties

The Role object defines several read-only properties:

Property Description DataType Nullable Unique Read Only
_embedded Embedded resources related to the Role assignment JSON HAL (opens new window) TRUE FALSE TRUE
_links Discoverable resources related to the Role assignment JSON HAL (opens new window) TRUE FALSE TRUE
assignmentType The type of assignment USER, GROUP FALSE FALSE TRUE
created Timestamp when the Role was assigned Date FALSE FALSE TRUE
id Unique key for the Role assignment String FALSE TRUE TRUE
label Display name of the Role String FALSE FALSE TRUE
lastUpdated Timestamp when the Role was last updated Date FALSE FALSE TRUE
status Status of the Role assignment ACTIVE FALSE FALSE TRUE
type Type of Role See the Role types table for a complete list. FALSE FALSE TRUE
resource-set The Resource Set ID in which the Role is granted (only present for Custom Roles) String TRUE TRUE TRUE

The following _links are returned:

  • assignee: Retrieves the User or Group to which this Role is assigned
  • resource-set: (Only for Custom Roles) Retrieves the Resource Set that is targeted by this assignment
  • permissions: (Only for Custom Roles) Lists all Permissions that are granted through this assignment
  • role: (Only for Custom Roles) Retrieves the Role that is granted through this assignment
  • member: (Only for Custom Roles) Retrieves the Member object from the Binding that grants this Role

Role types

Some Roles support optional targets that constrain the Role to a specific set of Groups or Apps. If an optional target isn't specified, then the Role assignment is unbounded (for example, applies to all Groups or Apps).

See the product documentation (opens new window) for a complete definition of permissions granted to each Role.

Role type Label Optional targets
API_ACCESS_MANAGEMENT_ADMIN API Access Management Administrator
APP_ADMIN Application Administrator Apps
GROUP_MEMBERSHIP_ADMIN Group Membership Administrator Groups
HELP_DESK_ADMIN Help Desk Administrator Groups
MOBILE_ADMIN Mobile Administrator
ORG_ADMIN Organizational Administrator
READ_ONLY_ADMIN Read-only Administrator
REPORT_ADMIN Report Administrator
SUPER_ADMIN Super Administrator
USER_ADMIN Group Administrator Groups
CUSTOM Custom Label specified by the client Groups

API_ACCESS MANAGEMENT_ADMIN is available if the API Access Management feature is enabled. See API Access Management Best Practices for a description of what the Role can do.

IAM-based Role types

Okta also supports the following IAM-based standard roles:

Role type Label Permissions
ACCESS_CERTIFICATIONS_ADMIN Access Certifications Administrator okta.governance.accessCertifications.manage
ACCESS_REQUESTS_ADMIN Access Requests Administrator okta.governance.accessRequests.manage

Assignment types

A Role could either be assigned to the User directly or be assigned to a Group of which the User is a Member. The assignee in _links provides more details about the User or the Group to which the assignment was made.

Assignment type Description
GROUP Role is assigned to an admin Group of which the User is a Member
USER Role is assigned to the User directly

Custom Role object

A Custom Role is a custom set of Permissions. A Custom Role is uniquely identified within your org by its ID or label.

Custom Role Properties

Property Description DataType Nullable Unique Read Only
id Unique key for the Role String FALSE TRUE TRUE
label Display name of the Role String FALSE TRUE FALSE
created The date and time the Role was created Timestamp FALSE FALSE TRUE
lastUpdated The date and time that the Role's label or description were last updated Timestamp FALSE FALSE TRUE
_links Discoverable resources related to the Role JSON HAL (opens new window) TRUE FALSE TRUE

Example

{
    "id": "cr0Yq6IJxGIr0ouum0g3",
    "label": "UserCreator",
    "description": "Create users",
    "created": "2021-02-06T16:20:57.000Z",
    "lastUpdated": "2021-02-06T16:20:57.000Z",
    "_links": {
    "permissions": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    }
  }
}

Permission types

Permissions can be added to, or removed from, Custom Roles. Permissions to manage a resource also grant the viewing privileges for the same resource so that you won't need to assign them separately.

User permissions are only effective regarding the Groups to which the admin is granted a Role through Resource Set assignments.

Permission properties

Property Description DataType Nullable Unique Read Only
label Type of permissions String FALSE FALSE TRUE
created The date and time the Permission was added to the role Timestamp FALSE FALSE TRUE
lastUpdated The date and time the Permission's association with the role was last updated Timestamp FALSE FALSE TRUE
_links Discoverable resources related to the Permission JSON HAL (opens new window) TRUE FALSE TRUE
Permission type Description Applicable resource types
okta.users.manage Allows the admin to create and manage Users and read all profile and credential information for Users. Delegated admins with this permission can only manage user credential fields and not the credential values themselves. All Users, all Users within a specific Group
okta.users.create Allows the admin to create Users. If the admin is also scoped to manage a Group, that admin can add the User to the Group on creation and then manage. All Groups, a specific Group
okta.users.read Allows the admin to read any User's profile and credential information. Delegated admins with this permission can only manage user credential fields and not the credential values themselves. All Users, all Users within a specific Group
okta.users.credentials.manage Allows the admin to manage only credential lifecycle operations for a User All users, all users within a specific group
okta.users.credentials.resetFactors Allows the admin to reset MFA authenticators for users All users, all users within a specific group
okta.users.credentials.resetPassword Allows the admin to reset passwords for users All users, all users within a specific group
okta.users.credentials.expirePassword Allows the admin to expire a user's password and set a new temporary password All Users, all Users within a specific Group
okta.users.userprofile.manage Allows the admin to only do operations on the User object, including hidden and sensitive attributes All Users, all Users within a specific Group
okta.users.lifecycle.manage Allows the admin to perform any User lifecycle operations All Users, all Users within a specific Group
okta.users.lifecycle.activate Allows the admin to activate user accounts All Users, all Users within a specific Group
okta.users.lifecycle.deactivate Allows the admin to deactivate user accounts All Users, all Users within a specific Group
okta.users.lifecycle.suspend Allows the admin to suspend user access to Okta. When a user is suspended, their user sessions are also cleared. All Users, all Users within a specific Group
okta.users.lifecycle.unsuspend Allows the admin to restore user access to Okta All Users, all Users within a specific Group
okta.users.lifecycle.delete Allows the admin to permanently delete user accounts All Users, all Users within a specific Group
okta.users.lifecycle.unlock Allows the admin to unlock users who have been locked out of Okta All Users, all Users within a specific Group
okta.users.lifecycle.clearSessions Allows the admin to clear all active Okta sessions and OAuth tokens for a user All Users, all Users within a specific Group
okta.users.groupMembership.manage Allows the admin to manage a user's group membership (also need okta.groups.members.manage to assign to a specific Group) All Users, all Users within a specific Group
okta.users.appAssignment.manage Allows the admin to manage a user's app assignment (also need okta.apps.assignment.manage to assign to a specific App) All Users, all Users within a specific Group
okta.groups.manage Allows the admin to fully manage Groups in your Okta organization All Groups, a specific Group
okta.groups.create Allows the admin to create Groups All Groups
okta.groups.members.manage Allows the admin to only manage member operations in a Group in your Okta org All Groups, a specific Group
okta.groups.read Allows the admin to only read information about Groups and their members in your Okta organization All Groups, a specific Group
okta.groups.appAssignment.manage Allows the admin to manage a Group's app assignment (also need okta.apps.assignment.manage to assign to a specific App) All Groups, a specific Group
okta.apps.read Allows the admin to only read information about Apps and their members in your Okta organization All Apps, All apps of specific type, a specific App
okta.apps.manage Allows the admin to fully manage Apps and their members in your Okta organization All Apps, All apps of specific type, a specific App
okta.apps.assignment.manage Allows the admin to manage assignment operations of an App in your Okta org and view the following provisioning errors: Application assignment, Group push mapping, and Error Profile push updates. All Apps, All apps of specific type, a specific App
okta.profilesources.import.run Allows the admin to run imports for apps with a profile source, such as HRaaS and AD/LDAP apps. Admins with this permission can create users through the import. All Apps, All apps of specific type, a specific App
okta.authzServers.read Allows the admin to read authorization servers All authorization servers, a specific authorization server
okta.authzServers.manage Allows the admin to manage authorization servers All authorization servers, a specific authorization server
okta.customizations.read Allows the admin to read customizations All customizations
okta.customizations.manage Allows the admin to manage customizations All customizations
okta.identityProviders.read Early Access Allows the admin to read Identity Providers All Identity Providers
okta.identityProviders.manage Early Access Allows the admin to manage Identity Providers All Identity Providers
okta.workflows.read Allows the admin to view delegated flows All Delegated Flows, a specific Delegated Flow
okta.workflows.invoke Allows the admin to view and run delegated flows All Delegated Flows, a specific Delegated Flow
okta.governance.accessCertifications.manage Allows the admin to view and manage access certification campaigns All Access Certifications
okta.governance.accessRequests.manage Allows the admin to view and manage Access Requests All Access Requests
okta.apps.manageFirstPartyApps Allows the admin to manage first-party apps All Access Requests
okta.directories.manage
Early Access
Allows the admin to manage all directory integration settings of an app instance All directory integrations, a specific type of directory integration, a specific directory integration
okta.directories.read
Early Access
Allows the admin to view the directory integration settings of an app instance All directory integrations, a specific type of directory integration, a specific directory integration
okta.devices.manage
Early Access
Allows the admin to manage devices and perform all device lifecycle operations All Devices
okta.devices.lifecycle.manage
Early Access
Allows the admin to perform any device lifecycle operations All Devices
okta.devices.lifecycle.activate
Early Access
Allows the admin to activate devices All Devices
okta.devices.lifecycle.deactivate
Early Access
Allows the admin to deactivate devices. When you deactivate a device, it loses all device user links. All Devices
okta.devices.lifecycle.suspend
Early Access
Allows the admin to suspend device access to Okta All Devices
okta.devices.lifecycle.unsuspend
Early Access
Allows the admin to unsuspend and restore device access to Okta All Devices
okta.devices.lifecycle.delete
Early Access
Allows the admin to permanently delete devices All Devices
okta.devices.read
Early Access
Allows the admin to read device details All Devices
okta.iam.read Allows the admin to view roles, resources, and admin assignments All Identity and Access Management resources

Note: Governance permissions are currently only supported as part of the Standard IAM-based Roles. You can't use these to create or update other roles.

Note: okta.apps.manageFirstPartyApps permission is only supported as part of some Standard IAM-based Roles. You can't use it to create or update other roles.

Note: okta.devices.* permissions are self-service Early Access. Turn on the Enable custom admin roles for device permissions feature from the Settings > Feature page in the Admin Console to access these permissions. See Manage Early Access and Beta features (opens new window).

Example

{
  "label" : "okta.users.read",
  "created": "2021-02-06T16:20:57.000Z",
  "lastUpdated": "2021-02-06T16:20:57.000Z",
  "_links": {
    "role": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3"
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/iam/roles/cr0Yq6IJxGIr0ouum0g3/permissions/okta.users.read"
    }
  }
}

Resource Set object

A Resource Set is a collection of resources. As there can be many resources in a set, the object itself doesn't list the resources but provides a paginated link to fetch resources.

Property Description DataType Nullable Unique Read Only
id Unique key for the Resource Set String FALSE TRUE TRUE
label Display name of the Resource Set String FALSE TRUE FALSE
description A description of the Resource Set String FALSE FALSE FALSE
_links Discoverable resources related to the Resource Set JSON HAL (opens new window) TRUE FALSE FALSE

The following _links are returned:

  • self: Retrieves the Resource Set
  • resources: Lists all resources included in this set
  • bindings: Lists all admin Role Bindings assigned to this set

Resource object

A resource has an ID and a link that points to the resource. Supported resources are:

Supported resources

The following are the supported resources.

Service Resource ORN Identifier REST URL
Directory All Users orn:${partition}:directory:${yourOrgId}:users https://${yourOktaDomain}/api/v1/users
All Groups orn:${partition}:directory:${yourOrgId}:groups https://${yourOktaDomain}/api/v1/groups
A specific Group orn:${partition}:directory:${yourOrgId}:groups:${groupId} https://${yourOktaDomain}/api/v1/groups/${groupId}
All Users within a specific Group orn:${partition}:directory:${yourOrgId}:groups:${groupId}:contained_resources https://${yourOktaDomain}/api/v1/groups/${groupId}/users
All Devices
Early Access
orn:${partition}:directory:${yourOrgId}:devices https://${yourOktaDomain}/api/v1/devices
Identity Provider All Apps orn:${partition}:idp:${yourOrgId}:apps https://${yourOktaDomain}/api/v1/apps
All Identity Providers Early Access orn:${partition}:idp:${yourOrgId}:identity_provider https://${yourOktaDomain}/api/v1/idps
All Apps of a specific type orn:${partition}:idp:${yourOrgId}:apps:${appType} https://${yourOktaDomain}/api/v1/apps/?filter=name+eq+%22${targetAppType}%22
A specific App orn:${partition}:idp:${yourOrgId}:apps:${appType}:${appId} https://${yourOktaDomain}/api/v1/apps/${appId}
All Authorization Servers orn:${partition}:idp:${yourOrgId}:authorization_servers https://${yourOktaDomain}/api/v1/authorizationServers
A specific Authorization Server orn:${partition}:idp:${yourOrgId}:authorization_servers:${authorizationServerId} https://${yourOktaDomain}/api/v1/authorizationServers/${authorizationServerId}
All customizations orn:${partition}:idp:${yourOrgId}:customizations
Workflows All Delegated Flows orn:${partition}:workflow:${yourOrgId}:flows
A specific Delegated Flow orn:${partition}:workflow:${yourOrgId}:flows:${flowId}
Governance All Access Certifications orn:$partition$:governance:$orgId$:certifications
All Access Requests orn:$partition$:governance:$orgId$:requests
Identity and Access Management All Identity and Access Management resources orn:$partition$:iam:$orgId$:contained_resources

The ID of a resource is unique to the Resource Set, whereas the link that points to the resource is unique for the org. A Group, if used in two Resource Sets, has distinct IDs in each Resource Set but has the same self link in both.

Note: Governance resources are currently only supported as part of the Standard Resource Sets. You can't use these to create or update other resource sets.

Resource examples

Group as resource
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3"
        }
      }
    }
Users of a Group as resource
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3/users"
        }
      }
    }
All Users as resource
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "users": {
          "href": "https://{yourOktaDomain}/api/v1/users"
        }
      }
    }
All Groups as resource
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "groups": {
          "href": "https://{yourOktaDomain}/api/v1/groups"
        }
      }
    }
All Apps as resource
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "apps": {
          "href": "https://{yourOktaDomain}/api/v1/apps"
        }
      }
    }
All Apps of the same type as resource
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "apps": {
          "href": "https://{yourOktaDomain}/api/v1/apps?filter=name+eq+%22workday%22"
        }
      }
    }
A specific app as resource
    {
      "id": "ire106sQKoHoXXsAe0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "apps": {
          "href": "https://{yourOktaDomain}/api/v1/apps/0oa1gjh63g214q0Hq0g4"
        }
      }
    }

Binding object

A Binding represents the assignment of a Custom Role to a list of admins. Bindings are specific to a Resource Set. There's a maximum of one Binding object per Role in a Resource Set.

The admin list assigned to a Role is made of Resource objects that represent either of the following types of admin assignments:

  • Directly assigned to the User
  • Assigned to a Group
Property Description DataType Nullable Unique Read Only
id ID of the Role granted in this Binding String FALSE FALSE FALSE
_links Discoverable resources related to the Resource Set JSON HAL (opens new window) TRUE FALSE FALSE

The following _links are returned:

  • self: Retrieves this Binding
  • members: Lists all Members included in this Binding

Member object

A Member has an ID and a link to the resource that represents the Role grantee. Supported resources are:

  • Groups
  • Users

The ID of a Member is unique to the Binding, whereas the link that points to the resource is unique for the org. The Group, if used in two Bindings, has distinct IDs in each but the same self link in both.

Member examples
Group as member
    {
      "id": "irb1q92TFAHzySt3x0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/groups/00guaxWZ0AOa5NFAj0g3"
        }
      }
    }
User as member
    {
      "id": "irb1qe6PGuMc7Oh8N0g4",
      "created": "2021-02-06T16:20:57.000Z",
      "lastUpdated": "2021-02-06T16:20:57.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/users/00uuk41Hjga5qGfQ30g3"
        }
      }
    }
Client Application as member
    {
      "id": "irb5vzkeQKc56r5G10g4",
      "created": "2022-12-14T00:00:00.000Z",
      "lastUpdated": "2022-12-14T00:00:00.000Z",
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/oauth2/v1/clients/0oa5vymVNCe2cPEeZ0g4"
        }
      }
    }

Condition object

Use a Condition object to further restrict a permission in a Custom Admin Role. For example, you can restrict access to specific profile attributes.

NOTE: Conditions are only available for okta.users.read and okta.users.userprofile.manage.

NOTE: You can't restrict admins from viewing certain attributes:

  • first name
  • last name
  • username
  • primary email
  • mobile phone

Condition object Properties

Property Description DataType Required
include Object with attributes to which access is allowed Object FALSE
exclude Object with attributes to which access isn't allowed Object FALSE

NOTE: Exactly one of include or exclude must be present in the conditions object.

Conditions example to include city, state, zipCode user attributes

{
  "conditions": {
    "include": {
      "okta:ResourceAttribute/User/Profile": [
        "city",
        "state",
        "zipCode"
      ]
    }
  }
}

Conditions example to include all user attributes except for city, state, zipCode

{
  "conditions": {
    "exclude": {
      "okta:ResourceAttribute/User/Profile": [
        "city",
        "state",
        "zipCode"
      ]
    }
  }
}