> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SCIM Security Event Tokens

> Send signed Security Event Tokens to your own receiver when SCIM changes users and groups, and verify them with Living Security's public keys.

> [!NOTE]
>
> This page is about sending events **out** to a receiver you run. To read the SCIM requests your identity provider sent **in**, see [Review received SCIM requests](https://docs.livingsecurity.com/features/settings/scim.md#review-received-scim-requests).

SCIM Events tell your systems when Living Security's SCIM service creates, changes, deactivates or deletes a user or group. Each event is a signed Security Event Token (SET), as RFC 9967 defines, pushed to an HTTPS receiver you run.

## What you need

* A native SCIM connection on the organization.
* The **Manage Identity Provider** permission.
* An HTTPS receiver on the public internet. Living Security does not send events to private, loopback, link-local or cloud metadata addresses, and does not follow redirects.

## Add a receiver

Add up to five receivers to a connection. For each receiver, choose:

| Setting | What it means |
| - | - |
| Endpoint | The HTTPS URL that receives events. |
| Audience | The `aud` value your receiver expects. The default is the endpoint URL. |
| Event families | Any of create, patch, put, delete, activate and deactivate. |
| Payload | **Notice** (default) sends attribute names only. **Full** sends the change's data, which includes personal data. Choose full only when your receiver may store that data. |
| Receiver residency | Where your receiver stores what it receives: US, EU or other. Living Security warns you when it is outside your organization's region. |

## What your receiver gets

Each event is an HTTP `POST` with `Content-Type: application/secevent+jwt`. The body is a compact JWS signed with ES256. The SET has these claims:

| Claim | Value |
| - | - |
| `iss` | Your region's SCIM base URL. |
| `aud` | The audience you set. |
| `jti` | A unique id. A resent event keeps the same `jti`. |
| `iat` | The time of the change. |
| `txn` | The id of the SCIM request that made the change. |
| `sub_id` | `{ "format": "scim", "uri": "/Users/{id}", "id": "{id}" }` |
| `events` | One or more RFC 9967 event URIs, for example `urn:ietf:params:scim:event:prov:patch:notice`. A PATCH or PUT that deactivates a user adds `urn:ietf:params:scim:event:prov:deactivate`. |

A notice event lists the changed attributes, for example `{ "attributes": ["emails", "title"] }`. A full event carries `data`. A delete event is empty.

## Verify each event

1. Read the `kid` from the JWS header.
2. Get your region's public keys from `{regional API host}/api/v1/scim/events/jwks.json`. Cache them, and fetch them again when you see a `kid` you do not know.
3. Check the signature, `typ` (`secevent+jwt`), `iss` and `aud`.
4. Store the event, then answer `202 Accepted`. Use `jti` to drop duplicates.

To refuse an event, answer `400` with `{ "err": "invalid_audience" }` or another RFC 8935 error code.

## Delivery and failures

* Events arrive in the order of the changes. When there is no backlog, an event arrives within about five minutes of its change.
* Each receiver gets at most 25 events every two minutes. A burst of changes therefore takes longer: for example, 100 changes take at least eight minutes to deliver.
* Only `202` counts as delivered. A server error, a timeout or any other success code is retried with the same `jti`.
* An event your receiver refuses with a 4xx is not sent again. The SCIM card shows the error.
* After a day of failures, at least ten in a row, the receiver becomes **dead** and gets no events. A receiver whose address becomes private is dead at once. Resume it on the SCIM card after you fix it; delivery continues from where it stopped.

## Discovery

While a connection has an active receiver, its `ServiceProviderConfig` includes `securityEvents` with the event URIs it sends and `"asyncRequest": "none"`. Living Security does not support `Prefer: respond-async` or polled delivery (RFC 8936).


## Related topics

- [SCIM security and best practices](https://docs.livingsecurity.com/features/settings/scim/security.md)
- [Living Security SCIM](https://docs.livingsecurity.com/features/settings/scim/overview.md)
- [Set up a SCIM connection](https://docs.livingsecurity.com/features/settings/scim/connection.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.