Identity events are the workspace-scoped operational log of SCIM user and group upserts, patches, and deprovisioning. They show resource identifiers, external correlation, success or error state, request ID, and timestamps.
Two authentication surfaces
The operator GET uses the browser session. Directory clients call /scim/v2 with a dedicated SCIM bearer token and application/scim+json; a workspace machine API key works on neither surface.
External IDs drive reconciliation
external_id and scim_resource_id connect an event to the directory and local SCIM resource. request_id is the best support correlation when an upstream request reports a failure.
Before you begin
A signed-in browser session with a selected workspace backed by an active membership is required; an archived workspace remains readable but rejects mutations. Every /api/v1/operator endpoint rejects API credentials and bearer tokens, regardless of their scopes.
Any role on an active membership can read SCIM sync events. This endpoint does not create SCIM tokens or provision identities itself.
Configure the enterprise directory and its SCIM bearer token through the workspace administration flow before expecting events.
How it works
Read newest outcomes
List sync events after a directory push and compare event_type, resource type, external ID, and status. A success confirms the application step; it does not prove the upstream directory has finished its own batch.
Investigate failures safely
Capture request_id and error_message, validate the directory mapping and token at the admin surface, then retry from the identity provider. Do not paste the SCIM token into an operator request.
Examples
These examples are illustrative. Replace the sample values with your own.
Keep credentials in environment variables or a secret manager, never in client-side code.
Read the SCIM sync log
This same-origin read observes directory activity without using or revealing the SCIM credential.
javascript
const response = await fetch("/api/v1/operator/scim_events", {
credentials: "same-origin",
headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);
What to expect
200 OK. The response wrapper is {"scim_sync_events": []}; populated events include event_type, scim_resource_type, external_id, status, error_message, and request_id.
Troubleshooting
The list is empty after provisioning
Confirm the directory called /scim/v2 rather than an operator URL and that the current workspace owns the token. Then use identity-provider logs to locate the request.
A machine bearer token gets 401
Operator identity history is deliberately session-only. A SCIM token authenticates only /scim/v2, and an agk_ credential authenticates only eligible public /api/v1 routes.
Endpoint reference
Ready to integrate? Open an endpoint for its required permissions, request fields,
response format, and status codes. The examples above explain the workflow;
these details define each individual request.
GET
/api/v1/operator/scim_events
Web Session
List SCIM sync events
Description
Returns recent SCIM provisioning events for the current workspace,
newest first. Browser session; machine Bearer tokens
(including tokens with identity scopes) are 401
"An authenticated operator session is required."
`limit` defaults to 50; larger values are clamped to 200, and zero,
negative or non-numeric values use 50. Logged `event_type`
values are `user.upsert`, `user.update`, `user.patch`,
`user.deprovision`, `group.upsert`, `group.update`, `group.patch`,
and `group.delete`. Mint and revoke SCIM bearer tokens on Workspace
admin (`/app/admin`), not `/app/workspace`.
Auth
Web Session
Parameters
Name
In
Type
Required
Description
limit
query
integer
No
Maximum events to return (default 50). Values above 200 are clamped to 200; zero, negative or non-numeric values use 50.
