Directories Integration

The Directories Integration API provides operations to manage Active Directory (AD) objects in a connected on-premises directory through Okta.

You can add or remove users from groups based on their identity and access requirements. This ensures that changes made to user access in Okta are reflected in AD. When you use Okta Access Certifications to revoke a user's membership to an AD group, the removal is reflected in AD.

Okta can only manage group memberships for users and groups imported into Okta using the AD integration. You can't use this API to manage users and groups that weren't imported through AD integration or are outside of the integration's org unit scope.

See Bidirectional Group Management.

Update an Active Directory group membership
OAuth 2.0:
  • okta.directories.groups.manage

Updates an Active Directory group membership directly in Active Directory

Note: See Before you begin: Active Directory integration with the following setup in the Use Okta Access Certifications to manage AD group membership product documentation.

Request
path Parameters
appInstanceId
required
string

ID of the Active Directory app instance in Okta

Request Body schema: application/json
required
id
string

ID of the Active Directory group to update

object (Parameters)

Attributes used for processing Active Directory group membership update

action
string

The update action to take

Enum: Description
ADD

Add to the membership of the group

REMOVE

Remove from the membership of the group

attribute
string

The attribute that tracks group memberships in Active Directory. For Active Directory, use member.

values
Array of strings

List of user IDs whose group memberships to update

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

502

There are no connected agents.

504

Timed out waiting for agent

post/api/v1/directories/{appInstanceId}/groups/modify
Request samples
application/json
{
  • "id": "00g1xucgTZFrziXg10g4",
  • "parameters": {
    • "action": "ADD",
    • "attribute": "member",
    • "values": [
      ]
    }
}
Response samples
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}