Directory sync LIVE

Two nightly jobs most institutions want: keep cost-center / WBS codes valid automatically, and administer group memberships when your directory can't map users to OpenIRIS groups on its own.

Cost centers (WBS codes)

Scopes: billing:read for reads, cost-centers:write for create/inactivate.

The sync recipe — diff by code, create on miss, inactivate on invalidation:

# 1. Does the code exist?
GET /v1/cost-centers?filter[code]=WBS4711

# 2a. Miss → create it (provider_id only needed on multi-provider keys)
POST /v1/cost-centers
Idempotency-Key: …
{ "code": "WBS4711", "name": "Microscopy core 2026" }

# 2b. Code no longer valid in SAP → inactivate (never delete)
GET  /v1/cost-centers/4501                # take the ETag from the response
PATCH /v1/cost-centers/4501
Idempotency-Key: …
If-Match: W/"9F27C1D44A50B1E3…"
{ "status": "inactive" }

Rules the API enforces for you:

code is ≤10 alphanumeric characters (SAP's cost-center limit) and unique per provider — a duplicate returns 409.
Cost centers are never deleted. Inactivation only stops the code being selectable for new bookings and charges; every historical charge keeps its reference. Reactivation ("status": "active") is allowed.
PATCH requires If-Match with the ETag from a prior GET — missing returns 428, stale returns 412 (re-GET and retry). This stops two admins/jobs from silently overwriting each other.

Group memberships

Scopes: users:read for reads, groups:write for member administration. Your key sees the groups of organisations that trust your provider(s).

GET    /v1/groups?filter[name][contains]=biology
GET    /v1/groups/8100/members

POST   /v1/groups/8100/members          # add — idempotent
Idempotency-Key: …
{ "user_id": 20117 }

DELETE /v1/groups/8100/members/20117    # remove — idempotent

Adding an existing member returns 200 with the current membership — not an error. Removing a non-member returns 204. Safe to re-run blindly.
Users are never auto-created. An unknown user_id returns 422. Users join OpenIRIS through the normal signup/SSO flow first; the API only manages their group placement.
Removals are archived exactly as removals made in the OpenIRIS UI are — the audit trail is identical.
Membership changes never retro-affect existing bookings or charge attribution.

There is deliberately no "replace all members" call. Group membership drives both access and billing attribution; a single faulty sync run against a replace-all endpoint would empty a group. Diff on your side and apply individual add/remove calls — both are idempotent, so partial failures are safely re-runnable.

Job hygiene

Run off-peak; both surfaces are small, a full diff of thousands of codes/members is a few hundred requests, comfortably within one key's rate budget.
Use a dedicated key per job (e.g. "SAP WBS sync") with only the scopes above — see the handbook on scope minimisation.
Log the trace_id of any non-2xx response; it is the fastest path through support.