SSF Streams

Developers
Home / Developers / SSF Streams

SSF Streams

Device Trust (Kolide) supports the Shared Signals Framework (SSF) for delivering device compliance events to external security systems, so you can orchestrate unified security policies across your entire stack. You can access SSF support with the Kolide Admin Console and the Kolide API.

SSF streams allow you to:

  • Configure receivers for Kolide compliance and device posture events
  • Deliver real-time device trust and risk signals to external security platforms
  • Control event delivery using push or poll
  • Test and validate event delivery
  • Retrieve and acknowledge delivered events

Requirements

To use SSF with Kolide, you need:

Manage SSF Streams in the Kolide Admin Console

An image showing the user interface for managing shared signals framework streams

To manage SSF streams:

  1. Select your profile in the top-right corner and choose Settings.
  2. Choose Developers > SSF Streams in the sidebar.

From here, you can add, view, edit, enable/disable, or delete streams.

Add a Stream

  1. Select Create New Stream.
  2. Enter a name for the stream.
  3. (Optional) Enter a URL:
    • A URL is required if you select Push.
    • A URL is optional if you select Poll.
  4. Set Delivery Type as Push or Poll.
  5. Set the Spec Version. Choose v1.0 for the standard format (sub_id at the top level). Only choose the draft version if you need compatibility with older receivers.
  6. Check the device_trust.status_changed box.
  7. Select Save.

View Stream Events

  1. In the SSF streams table, select the stream you want to view.
  2. Under “Events” you can view the events for that stream.

Edit a Stream

  1. In the SSF streams table, select the stream you want to edit.
  2. In the top-right corner, select the Actions dropdown.
  3. You can change the name, URL, delivery type (push or poll), and event type.
  4. Select Save.

Turn a Stream On or Off

In the SSF streams table, find the stream in the table and toggle the Status on or off.

Delete a Stream

  1. In the SSF streams table, select the stream you want to delete.
  2. In the top-right corner, select the Actions dropdown > Delete.

Manage SSF Streams with the API

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 2026-04-07.

Create an SSF Stream

Create a new SSF stream to configure an event receiver. The endpoint accepts two request body formats:

  • The standard SSF Create Stream body. This is recommended for SSF-compliant receivers and is the shape advertised by the configuration_endpoint in our well-known metadata.
  • The Kolide legacy body wrapped in ssf_stream. This is used by the in-app UI and existing Kolide API integrations.

Both forms create the same stream and return the same response shape.

Standard SSF Create Stream Body

curl --location 'https://api.kolide.com/ssf_streams' \
--header 'X-Kolide-Api-Version: <version>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "name": "Example Receiver",
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/web"
    },
    "events_requested": ["https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"]
}'
  • delivery.method must be urn:ietf:rfc:8935 (push) or urn:ietf:rfc:8936 (poll).
  • delivery.endpoint_url is the receiver URL Kolide will deliver events to for push streams. For poll streams, it is informational.
  • events_requested currently only supports the device compliance change event.
  • You do not need to send aud. Kolide assigns it on the transmitter side and returns it in the response.

Kolide Legacy Body

Create a Push Stream

To create a push stream, include a valid aud URL and set delivery_type to push.

  • The aud field for push streams must be an https:// URL that points to a publicly-reachable host.
  • URLs that target unencrypted http:// addresses, localhost, loopback addresses (127.x.x.x), or RFC 1918 private network ranges (10.x.x.x, 192.168.x.x, 172.16.x.x – 172.31.x.x) are rejected with a validation error.
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://example.com/web",
      "delivery_type": "push",
      "event_subscriptions": ["https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"]
    }
}'
  • delivery_type must be either push or poll.
  • event_subscriptions currently only supports the device compliance change event.

Example JSON response for a new push 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"
],
"events_requested": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change",
"https://schemas.openid.net/secevent/ssf/event-type/verification"
],
"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"
}
}

Create a Poll Stream

To create a poll stream, set delivery_type to poll.

  • The response will include a one-time poll_bearer_token used for all subsequent poll and acknowledge requests. Save the poll bearer token when you create the stream. The token is provided only once and can’t be recovered later.
  • If you lose the token, or want to rotate it, you’ll need to delete the stream and create a new one. The new stream will receive a fresh poll_bearer_token along with a new stream_id, so be sure to update both values in your receiver’s configuration.
  • Streams created before poll bearer tokens were introduced don’t have a poll bearer token assigned. Those legacy streams will continue to accept poll and acknowledge requests without the X-Kolide-Poll-Bearer-Token header.
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 Polling Receiver",
      "delivery_type": "poll",
      "event_subscriptions": ["https://schemas.openid.net/secevent/caep/event-type/device-compliance-change"]
    }
}'

Example JSON response for a new polling SSF stream

 
{
"id": "1",
"iss": "https://api.kolide.com",
"stream_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Example Polling Receiver",
"aud": null,
"delivery_type": "poll",
"enabled": true,
"poll_bearer_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"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:8936"
}
}

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"
],
"events_requested": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change",
"https://schemas.openid.net/secevent/ssf/event-type/verification"
],
"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 the stream id or stream_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"
],
"events_requested": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change",
"https://schemas.openid.net/secevent/ssf/event-type/verification"
],
"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"
],
"events_requested": [
"https://schemas.openid.net/secevent/caep/event-type/device-compliance-change",
"https://schemas.openid.net/secevent/ssf/event-type/verification"
],
"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"
}'

Test a stream example response

 
{
"success": true,
"response_code": "200",
"ssf_stream_event_id": 1
}

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"
],
"configuration_endpoint": "https://api.kolide.com/ssf_streams",
"verification_endpoint": "https://api.kolide.com/ssf_streams/{stream_id}/test"
}

Poll for SSF Events

Use polling to retrieve SSF events for a stream. Include the poll_bearer_token returned when the stream was created in the X-Kolide-Poll-Bearer-Token header.

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

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_id is returned when the stream is created.

Include the poll_bearer_token returned when the stream was created in the X-Kolide-Poll-Bearer-Token header.

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

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


By accessing or using 1Password Developer Tools, you agree to the API and SDK Terms of Service.