Group Push Mappings

The Group Push Mappings API provides operations to manage group push mappings for your org. You must have provisioning enabled in the target app to use group push mappings. See Manage Group Push.

List all group push mappings
OAuth 2.0 scopes:
  • okta.apps.read
  • okta.groups.read

Lists all group push mappings with pagination support

Request
path Parameters
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
query Parameters
after
string

Specifies the pagination cursor for the next page of mappings

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Specifies the number of results returned

lastUpdated
string

Filters group push mappings by last updated date. The lastUpdated parameter supports the following format: YYYY-MM-DDTHH:mm:ssZ. This filters mappings updated on or after the specified date and time in UTC.

If you don't specify a value, all group push mappings are returned.

Example: lastUpdated=2025-01-01T00:00:00Z
sourceGroupId
string

Filters group push mappings by source group ID. If you don't specify a value, all group push mappings are returned.

Example: sourceGroupId=00g00000000000000000
status
string (GroupPushMappingStatus)

Filters group push mappings by status. If you don't specify a value, all group push mappings are returned.

Enum: Description
ACTIVE

The group push mapping is active and Okta pushes membership changes to the target group

INACTIVE

The group push mapping is inactive and Okta doesn't push membership changes to the target group

ERROR

The group push mapping is in an error state and Okta doesn't push membership changes to the target group

Responses
200

OK

401

Unauthorized

403

Forbidden

429

Too Many Requests

get/api/v1/apps/{appId}/group-push/mappings
Request samples 
Response samples 
application/json
[]
Create a group push mapping
OAuth 2.0 scopes: 
  • okta.apps.manage
  • okta.groups.manage
Creates or links a group push mapping.


Note: Either targetGroupId or targetGroupName must be provided, but not both. If targetGroupId is provided, it links to an existing group. If targetGroupName is provided, it creates a new group.


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Request Body schema: application/json
required
sourceGroupId
required
string
The ID of the source group for the group push mapping


 
object (AppConfig) 
Additional app configuration for group push mappings. Currently only required for Active Directory.


 
distinguishedName
required
string
The distinguished name of the group in Active Directory


 
groupScope
required
string (ActiveDirectoryGroupScope) 
The scope of the group in Active Directory


 Enum: "DOMAIN_LOCAL" "GLOBAL" "UNIVERSAL"  
groupType
required
string (ActiveDirectoryGroupType) 
The type of the group in Active Directory


 Enum: "DISTRIBUTION" "SECURITY"  
samAccountName
required
string
The SAM account name of the group in Active Directory


 
type
required
string (AppConfigType) 
The type of the app configuration


 
status
string (GroupPushMappingStatus) 
 Default:  "ACTIVE"
The status of the group push mapping


 Enum: "ACTIVE" "INACTIVE"  
targetGroupId
string
The ID of the existing target group for the group push mapping. This is used to link to an existing group. Required if targetGroupName is not provided.


 
targetGroupName
string
The name of the target group for the group push mapping. This is used when creating a new downstream group. If the group already exists, it links to the existing group. Required if targetGroupId is not provided.


 
Responses 
201
Created


400
Bad Request


401
Unauthorized


403
Forbidden


429
Too Many Requests


post/api/v1/apps/{appId}/group-push/mappings
Request samples 
application/json
{
  • "sourceGroupId": "00g00000000000000000",
  • "status": "ACTIVE",
  • "targetGroupName": "NewGroup"
}
Response samples 
application/json
{}
Retrieve a group push mapping
OAuth 2.0 scopes: 
  • okta.apps.read
  • okta.groups.read
Retrieves a group push mapping by ID


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
mappingId
required
string
Group push mapping ID


 
 Example:  gPm00000000000000000
Responses 
200
OK


401
Unauthorized


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/apps/{appId}/group-push/mappings/{mappingId}
Request samples 
Response samples 
application/json
{}
Update a group push mapping
OAuth 2.0 scopes: 
  • okta.apps.manage
  • okta.groups.manage
Updates the status of a group push mapping


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
mappingId
required
string
Group push mapping ID


 
 Example:  gPm00000000000000000
Request Body schema: application/json
required
status
required
string (GroupPushMappingStatus) 
 Default:  "ACTIVE"
The status of the group push mapping


 Enum: "ACTIVE" "INACTIVE"  
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


404
Not Found


429
Too Many Requests


patch/api/v1/apps/{appId}/group-push/mappings/{mappingId}
Request samples 
application/json
{
  • "status": "INACTIVE"
}
Response samples 
application/json
{}
Delete a group push mapping
OAuth 2.0 scopes: 
  • okta.apps.manage
  • okta.groups.manage
Deletes a specific group push mapping. The group push mapping must be in an INACTIVE state.


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
mappingId
required
string
Group push mapping ID


 
 Example:  gPm00000000000000000
query Parameters
deleteTargetGroup
required
boolean
 Default:  false
If set to true, the target group is also deleted. If set to false, the target group isn't deleted.


 
Responses 
204
No Content


401
Unauthorized


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/apps/{appId}/group-push/mappings/{mappingId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000011",
  • "errorSummary": "Invalid token provided",
  • "errorLink": "E0000011",
  • "errorId": "sampleQPivGUj_ND5v78vbYWW",
  • "errorCauses": [ ]
}