Group Rules

The Group Rules API provides operations to manage rules for Okta Groups in your org.

List all group rules
OAuth 2.0: okta.groups.read

Lists all Group rules for your org

Request
query Parameters
limit
integer <int32> [ 1 .. 200 ]
Default: 50

Specifies the number of rule results in a page

after
string

Specifies the pagination cursor for the next page of rules

search
string

Specifies the keyword to search rules for

expand
string

If specified as groupIdToGroupNameMap, then displays group names

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/groups/rules
Request samples 
Response samples 
application/json
List all group rules example


[
  • {
    • "type": "group_rule",
    • "id": "0pr3f7zMZZHPgUoWO0g4",
    • "status": "INACTIVE",
    • "name": "Engineering group rule",
    • "created": "2016-12-01T14:40:04.000Z",
    • "lastUpdated": "2016-12-01T14:40:04.000Z",
    • "conditions": {
      },
    • "actions": {
      }
    }
]
Create a group rule
OAuth 2.0: okta.groups.manage
Creates a Group rule to dynamically add Users to the specified Group if they match the condition




Note: Group rules are created with the status set to 'INACTIVE'.




Request 
Request Body schema: application/json
required
object (GroupRuleAction) 
Defines which users and groups to assign


 
object (GroupRuleGroupAssignment) 
Contains the groupIds array


 
groupIds
Array of strings
Array of groupIds to which Users are added


 
object (GroupRuleConditions) 
Defines group rule conditions


 
object (GroupRuleExpression) 
Defines Okta specific group-rules expression


 
type
string
Expression type. Only valid value is 'urn:okta:expression:1.0'.


 
value
string
Okta expression that would result in a Boolean value


 
object (GroupRulePeopleCondition) 
Defines conditions for people in a group rule


 
object (GroupRuleGroupCondition) 
Currently not supported


 
object (GroupRuleUserCondition) 
Defines conditions specific to user exclusion


 
name
string  [ 1 .. 50 ] characters 
Name of the Group rule


 
type
string
 Value: "group_rule"  
Responses 
200
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/groups/rules
Request samples 
application/json
{
  • "type": "group_rule",
  • "name": "Engineering group rule",
  • "conditions": {
    • "people": {
      },
    • "expression": {
      }
    },
  • "actions": {
    • "assignUserToGroups": {
      }
    }
}
Response samples 
application/json
Example of a group rule


{
  • "type": "group_rule",
  • "id": "0pr3f7zMZZHPgUoWO0g4",
  • "status": "INACTIVE",
  • "name": "Engineering group rule",
  • "created": "2016-12-01T14:40:04.000Z",
  • "lastUpdated": "2016-12-01T14:40:04.000Z",
  • "conditions": {
    • "people": {
      },
    • "expression": {
      }
    },
  • "actions": {
    • "assignUserToGroups": {
      }
    }
}
Retrieve a group rule
OAuth 2.0: okta.groups.read
Retrieves a specific Group rule by ID from your org


Request 
path Parameters
groupRuleId
required
string
The id of the group rule


 
 Example:  0pr3f7zMZZHPgUoWO0g4
query Parameters
expand
string
If specified as groupIdToGroupNameMap, then show Group names


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/groups/rules/{groupRuleId}
Request samples 
Response samples 
application/json
Example of a group rule


{
  • "type": "group_rule",
  • "id": "0pr3f7zMZZHPgUoWO0g4",
  • "status": "INACTIVE",
  • "name": "Engineering group rule",
  • "created": "2016-12-01T14:40:04.000Z",
  • "lastUpdated": "2016-12-01T14:40:04.000Z",
  • "conditions": {
    • "people": {
      },
    • "expression": {
      }
    },
  • "actions": {
    • "assignUserToGroups": {
      }
    }
}
Replace a group rule
OAuth 2.0: okta.groups.manage
Replaces a Group rule




Notes: You only can update rules with a Group whose status is set to 'INACTIVE'.


You currently can't update the action section.




Request 
path Parameters
groupRuleId
required
string
The id of the group rule


 
 Example:  0pr3f7zMZZHPgUoWO0g4
Request Body schema: application/json
required
object (GroupRuleAction) 
Defines which users and groups to assign


 
object (GroupRuleGroupAssignment) 
Contains the groupIds array


 
groupIds
Array of strings
Array of groupIds to which Users are added


 
object (GroupRuleConditions) 
Defines group rule conditions


 
object (GroupRuleExpression) 
Defines Okta specific group-rules expression


 
type
string
Expression type. Only valid value is 'urn:okta:expression:1.0'.


 
value
string
Okta expression that would result in a Boolean value


 
object (GroupRulePeopleCondition) 
Defines conditions for people in a group rule


 
object (GroupRuleGroupCondition) 
Currently not supported


 
object (GroupRuleUserCondition) 
Defines conditions specific to user exclusion


 
name
string  [ 1 .. 50 ] characters 
Name of the Group rule


 
status
string (GroupRuleStatus) 
Status of group rule


 Enum: "ACTIVE" "INACTIVE" "INVALID"  
type
string
Type to indicate a Group rule operation. Only group_rule is allowed.


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/groups/rules/{groupRuleId}
Request samples 
application/json
Example of a group rule


{
  • "type": "group_rule",
  • "id": "0pr3f7zMZZHPgUoWO0g4",
  • "status": "INACTIVE",
  • "name": "Engineering group rule",
  • "created": "2016-12-01T14:40:04.000Z",
  • "lastUpdated": "2016-12-01T14:40:04.000Z",
  • "conditions": {
    • "people": {
      },
    • "expression": {
      }
    },
  • "actions": {
    • "assignUserToGroups": {
      }
    }
}
Response samples 
application/json
{
  • "actions": {
    • "assignUserToGroups": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "people": {
      }
    },
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "status": "ACTIVE",
  • "type": "string"
}
Delete a group rule
OAuth 2.0: okta.groups.manage
Deletes a specific group rule by groupRuleId


Request 
path Parameters
groupRuleId
required
string
The id of the group rule


 
 Example:  0pr3f7zMZZHPgUoWO0g4
query Parameters
removeUsers
boolean
 Default:  false
If set to true, removes Users from Groups assigned by this rule


 
Responses 
202
Accepted


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/groups/rules/{groupRuleId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Activate a group rule
OAuth 2.0: okta.groups.manage
Activates a specific Group rule by ID from your org


Request 
path Parameters
groupRuleId
required
string
The id of the group rule


 
 Example:  0pr3f7zMZZHPgUoWO0g4
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/groups/rules/{groupRuleId}/lifecycle/activate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Deactivate a group rule
OAuth 2.0: okta.groups.manage
Deactivates a specific Group rule by ID from your org


Request 
path Parameters
groupRuleId
required
string
The id of the group rule


 
 Example:  0pr3f7zMZZHPgUoWO0g4
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/groups/rules/{groupRuleId}/lifecycle/deactivate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}