PATCH | Partially update LDAP group sync by [id]

Description

Change selected settings of an LDAP group synchronization in the Segura™ platform without sending the whole resource. The endpoint follows JSON Merge Patch, defined in RFC 7396: the fields you send are changed, the fields you omit keep their stored values, and a field set to null returns to its default.

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 current ETag of the synchronization, returned by GET | List an LDAP group sync by [id].

Request

PATCH /api/v2/iam/ldap-group-syncs/[id]

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/merge-patch+json`. Any other value returns `415`.
`If-Match`	Yes	The `ETag` of the synchronization as it was last read.

Request body

Every field is optional. The fields accepted are the same as POST | Create LDAP group sync, with the same types, limits, and allowed values.

Sending a read-only field returns 422 patch.field.not.allowed. The read-only fields are id, active, last_sync_at, last_sync_succeeded, created_at, updated_at, and tenant_code.

Attention

The active state is not patchable. To change it, access POST | Activate LDAP group sync or POST | Deactivate LDAP group sync.

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

Body

{
    "group_sync": {
        "synchronization_enabled": false
    }
}

Response

HTTP/1.1 200 OK
ETag: "3bd6e0c95a17f482"

The ETag header holds the new version of the synchronization. The body carries the complete canonical model, the same as GET | List an LDAP group sync by [id], not only the fields that changed.

Example response body

{
    "data": {
        "id": "501",
        "group_sync": {
            "name": "Infrastructure operators",
            "active": true,
            "server": { "id": "10" },
            "user_group": { "id": "7" },
            "synchronization_enabled": false,
            "overwrite_user_accesses": false,
            "force_roles": true,
            "automatic_sync": false,
            "dn": "OU=Operators,DC=example,DC=com",
            "ad_username_attribute": "sAMAccountName",
            "ad_name_attribute": "displayname",
            "department": null,
            "ad_query": "(&(objectClass=group)(cn=ops-*))",
            "roles": [{ "id": 1 }, { "id": 3 }]
        },
        "domum": {
            "enabled": true,
            "type": "limited_users",
            "vendor": { "id": 22 }
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-group-syncs/501" },
        "actions": {
            "sync": "/api/v2/iam/ldap-group-syncs/501/sync",
            "deactivate": "/api/v2/iam/ldap-group-syncs/501/deactivate"
        }
    }
}

Response body fields

The response fields match GET | List an LDAP group sync by [id].

Errors

HTTP code	Message	Possible cause	Solution
`400`	`api.request.malformed`	The body is not valid JSON.	Check the JSON syntax and resend the request.
`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.
`412`	`api.precondition.failed`	The `If-Match` value does not match the stored version.	Read the resource again, review the change, and resend the request with the new `ETag`.
`415`	`Unsupported Media Type`	`Content-Type` is not `application/merge-patch+json`.	Set the header to `application/merge-patch+json`.
`428`	`api.precondition.required`	The `If-Match` header is missing.	Read the resource, then resend the request with its `ETag` in `If-Match`.
`422`	`patch.field.not.allowed`	The body carries a read-only field.	Remove `id`, `active`, `last_sync_at`, `last_sync_succeeded`, `created_at`, `updated_at`, and `tenant_code`.
`422`	`api.validation.invalid_reference`	A referenced resource does not exist.	Confirm the referenced resources exist before you resend the request.
`422`	`api.validation.overwrite.requires_sync_enabled`	The result of the patch would set `overwrite_user_accesses` to `true` while `synchronization_enabled` is `false`.	Send both fields consistently in the same request.
`422`	`api.enum.invalid_value`	`ad_name_attribute` or `domum.type` is outside its allowed values.	Send one of the allowed values.
`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.