SSF Streams (beta)

Beta Feature:

Shared Signals Framework support is currently in beta and subject to change. To enable SSF access during the beta, contact Kolide Support.

Kolide supports the Shared Signals Framework (SSF) for delivering device compliance events to external security systems. SSF support is currently only available through the Kolide API.

SSF streams allow you to:

Configure receivers for Kolide compliance events
Control event delivery using push or polling
Test and validate event delivery
Retrieve and acknowledge delivered events

Requirements

To use SSF with Kolide, you need:

An API key with the special write permission to Manage Shared Signals Framework Streams. Follow the steps to create an API key in Kolide.
1Password Device Trust Core or 1Password Device Trust Connect. Contact Kolide support to upgrade.

All SSF requests must include:

A valid API token passed in the Authorization header.
A valid X-Kolide-Api-Version header. The current API version is 2023-05-26.

Manage SSF Streams

Create an SSF stream

Create a new SSF stream to configure an event receiver.

delivery_type must be either push or poll.
event_subscriptions currently only supports the device compliance change event.

curl --location 'https://api.kolide.com/ssf_streams' \
--header 'X-Kolide-Api-Version: <version>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "ssf_stream": {
      "name": "Example Receiver",
      "aud": "https://receiver.example.com/web",
      "delivery_type": "push",
      "event_subscriptions": ["https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"]
    }
}'

Example JSON response for the new SSF stream

{
"id": "1",
"iss": "https://api.kolide.com",
"stream_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Example Receiver",
"aud": "https://receiver.example.com/web",
"delivery_type": "push",
"enabled": true,
"events_supported": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"
],
"created_at": "2026-01-23T21:45:43.998Z",
"updated_at": "2026-01-23T21:45:43.998Z",
"delivery": {
"method": "urn:ietf:rfc:8935",
"endpoint_url": "https://receiver.example.com/web"
}
}

Get all SSF streams

Retrieve a list of all SSF streams configured for your organization.

curl --location 'https://api.kolide.com/ssf_streams' \
--header 'X-Kolide-Api-Version: <version>' \
--header 'Authorization: Bearer <token>'

Example response with a list of SSF streams

{
"data": [
{
"id": "1",
"iss": "https://api.kolide.com",
"stream_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Example Receiver",
"aud": "https://receiver.example.com/web",
"delivery_type": "push",
"enabled": true,
"events_supported": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"
],
"created_at": "2026-01-23T21:45:43.998Z",
"updated_at": "2026-01-23T21:45:43.998Z",
"delivery": {
"method": "urn:ietf:rfc:8935",
"endpoint_url": "https://receiver.example.com/web"
}
}
],
"pagination": {
"next": "",
"next_cursor": "",
"current_cursor": "",
"count": 1
}
}

Get a single SSF stream

Retrieve details for a specific SSF stream by ID.

curl --location 'https://api.kolide.com/ssf_streams/1' \
--header 'X-Kolide-Api-Version: <version>' \
--header 'Authorization: Bearer <token>'

Get a single stream example response

{
"id": "1",
"iss": "https://api.kolide.com",
"stream_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Example Receiver",
"aud": "https://receiver.example.com/web",
"delivery_type": "push",
"enabled": true,
"events_supported": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"
],
"created_at": "2026-01-23T21:45:43.998Z",
"updated_at": "2026-01-23T21:45:43.998Z",
"delivery": {
"method": "urn:ietf:rfc:8935",
"endpoint_url": "https://receiver.example.com/web"
}
}

Update an SSF stream

Update an existing SSF stream to change its name, aud, delivery_type, or event_subscriptions.

curl --location --request PATCH 'https://api.kolide.com/ssf_streams/1' \
--header 'X-Kolide-Api-Version: <version>' \
--header  'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "ssf_stream": {
    "name": "New Name"
    }
}'

Update a stream example response

{
"id": "1",
"iss": "https://api.kolide.com",
"stream_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "New Name",
"aud": "https://receiver.example.com/web",
"delivery_type": "push",
"enabled": true,
"events_supported": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"
],
"created_at": "2026-01-23T21:45:43.998Z",
"updated_at": "2026-01-23T21:51:00.031Z",
"delivery": {
"method": "urn:ietf:rfc:8935",
"endpoint_url": "https://receiver.example.com/web"
}
}

Testing an SSF stream

You can send a test event to verify delivery. Test events require an email address.

curl --location 'https://api.kolide.com/ssf_streams/1/test' \
--header 'X-Kolide-Api-Version: <version>' \
--header  'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "email": "johnappleseed@kolide.co"
}'

Well-known SSF configuration

Kolide provides a well-known SSF configuration endpoint for discovery.

curl --location 'https://api.kolide.com/.well-known/ssf-configuration'

Well-known configuration example response

{
"issuer": "https://api.kolide.com",
"jwks_uri": "https://api.kolide.com/ssf/jwks.json",
"delivery_methods_supported": [
"urn:ietf:rfc:8935",
"urn:ietf:rfc:8936"
],
"events_supported": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"
]
}

Poll for SSF events

Use polling to retrieve SSF events for a stream.

curl -X GET "https://api.kolide.com/ssf_streams/<stream_uuid>/events" \
--header 'Authorization: Bearer <token>' \
--header 'X-Kolide-Api-Version: <version>'

Polling for SSF events example response

{
"sets": {
"abc123-uuid": "eyJhbGciOiJSUzI1NiIsInR5cCI6InNlY2V2ZW50K2p3dCJ9..."
}
}

Acknowledge the polled SSF events

For polled SSF events, you need to acknowledge receipt of the events so they’re not returned in future poll requests.

The stream UUID is the stream_id returned when the stream was created.

The JTI is the event identifier returned in the polling response.

curl -X POST "https://api.kolide.com/ssf_streams/<stream_uuid>/events" \
--header 'X-Kolide-Api-Version: <version>' \
--header  'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
 -d "{
    \"ack\": [\"${JTI}\"]
  }"