POST | Run LDAP group sync

Description

Start an LDAP group synchronization run in the Segura™ platform. The run creates and updates the users found in the Active Directory group, propagates their ACL roles, and reprocesses the related access policies.

The work is asynchronous. The platform queues it and answers immediately with a job descriptor, so the response confirms the run was accepted, not that it finished.

Prerequisites

An application with the Users authorization granted by the administrator in A2A, and its resource permission set to Read and write. For more information, access How to manage authorizations in A2A.
A valid OAuth 2.0 access token. For more information, access How to authenticate an application in A2A.
The synchronization must be active. Running an inactive synchronization returns 409.

Request

POST /api/v2/iam/ldap-group-syncs/[id]/sync

Path parameters

Field	Type	Required	Description
`id`	int	Yes	Unique identification code of the synchronization.

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`, even though the request carries no body.

Example request `POST` `{{url}}/api/v2/iam/ldap-group-syncs/501/sync`

Response

HTTP/1.1 202 Accepted
Location: /api/v2/iam/jobs/job-7b3f

The Location header holds the path of the job created for this run. Poll that path to follow the outcome.

Example response body

{
    "data": {
        "job": {
            "id": "job-7b3f",
            "type": "sync",
            "state": "queued"
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/jobs/job-7b3f" }
    }
}

Response body fields

Field	Type	Description
`data`	object	The job created for this run.
`meta`	object	Links for the job.

`data.job`

Field	Type	Description
→→`id`	string	Unique identification code of the job. Use it to poll the job status.
→→`type`	string	The kind of work queued. Returns `sync` for this action.
→→`state`	string	State of the job at the moment of the response. A newly accepted job returns `queued`.

`meta.links`

Field	Type	Description
→→`self`	string	Path of the job, matching the `Location` header.

Info

The job status and retry endpoints are shared across the iam resources and are documented separately.

Errors

HTTP code	Message	Possible cause	Solution
`403`	`api.permission.denied`	The application lacks permission for this resource.	Ask the administrator to check the application's Users authorization in A2A.
`404`	`api.resource.not_found`	No synchronization exists with the identification code sent.	Check the `id` and resend the request.
`409`	`api.resource.inactive`	The synchronization is inactive.	Activate it with [POST
`429`	`rate_limit_exceeded`	The application exceeded its request quota.	Wait for the period in the `Retry-After` header and resend the request.

Authentication errors

Message	Possible cause	Solution
`Client authentication failed.`	Application authentication failure with the Segura server.	Check the authentication parameters (`Access Token URL`, `Client ID`, and `Client secret`) and request a new access token.
`Invalid signature`	Failure in recognizing the client application URL.	Check the URL of the client application and resend the request.
`No route matched with those values.`	Missing authorization header in the API request.	Request a new access token.
`Request timed out.`	The request exceeded the timeout limit.	Check the connectivity between the source of the request and the Segura server.