SSF Transmitter

Note: The SSF Transmitter API is a self-service Early Access (EA) feature. You must enable the Enable Managed Apple ID federation and provisioning feature in your Org settings to access this feature. See Manage Early Access and Beta features.

Okta uses the Shared Signals Framework (SSF) to send security-related events and other data-subject signals to third-party security vendors. In this scenario, commonly used terms for third-party vendors that receive signals are "receivers", Okta is the "transmitter", and the connection between the two entities is referred to as a "stream."

The SSF Transmitter API allows you to manage SSF stream configurations between the receiver that receives signals transmitted by Okta. Okta sends signals in the form of Security Event Tokens (SETs) to a third-party SSF receiver. To enable the transmission of signals from Okta, you must create an SSF Stream using the SSF Transmitter API and configure the third-party receiver to accept signals from Okta.

Retrieve the SSF Transmitter metadata
Early AccessIdentity Engine

Retrieves SSF Transmitter configuration metadata. This includes all supported endpoints and key information about certain properties of the Okta org as the transmitter, such as delivery_methods_supported, issuer, and jwks_uri.

Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

get/.well-known/ssf-configuration
Request samples
Response samples
application/json
{}

Retrieve the SSF Stream configuration(s)
Early AccessIdentity Engine
OAuth 2.0: ssf.read

Retrieves either a list of all known SSF Stream configurations or the individual configuration if specified by ID.

As Stream configurations are tied to a Client ID, only the Stream associated with the Client ID of the request OAuth 2.0 access token can be viewed.

Request
query Parameters
stream_id
string

The ID of the specified SSF Stream configuration

Example: stream_id=esc1k235GIIztAuGK0g5
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/ssf/stream
Request samples
Response samples
application/json

Create an SSF Stream
Early AccessIdentity Engine
OAuth 2.0: ssf.manage

Creates an SSF Stream for an event receiver to start receiving security events in the form of Security Event Tokens (SETs) from Okta.

An SSF Stream is associated with the Client ID of the OAuth 2.0 access token used to create the stream. The Client ID is provided by Okta for an OAuth 2.0 app integration. One SSF Stream is allowed for each Client ID, hence, one SSF Stream is allowed for each app integration in Okta.

A maximum of 10 SSF Stream configurations can be created for one org.

Request
Request Body schema: application/json
required
events_requested
required
Array of strings <uri> <= 50 items

The events (mapped by the array of event type URIs) that the receiver wants to receive

required
object (Stream Configuration Delivery)

Contains information about the intended SET delivery method by the receiver

method
required
string

The delivery method that the transmitter uses for delivering a SET

Enum: "https://schemas.openid.net/secevent/risc/delivery-method/push" "urn:ietf:rfc:8935"
endpoint_url
required
string <uri> <= 2048 characters

The target endpoint URL where the transmitter delivers the SET using HTTP POST requests

authorization_header
string or null <= 8192 characters

The HTTP Authorization header that is included for each HTTP POST request

format
string

The Subject Identifier format expected for any SET transmitted.

Value: "iss_sub"
Responses
201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

429

Too Many Requests

post/api/v1/ssf/stream
Request samples
application/json
{}
Response samples

Replace an SSF Stream
Early AccessIdentity Engine
OAuth 2.0: ssf.manage

Replaces all properties for an existing SSF Stream configuration.

If the stream_id isn't provided in the request body, the associated stream with the Client ID (through the request OAuth 2.0 access token) is replaced.

Request
Request Body schema: application/json
required
events_requested
required
Array of strings <uri> <= 50 items

The events (mapped by the array of event type URIs) that the receiver wants to receive

required
object (Stream Configuration Delivery)

Contains information about the intended SET delivery method by the receiver

method
required
string

The delivery method that the transmitter uses for delivering a SET

Enum: "https://schemas.openid.net/secevent/risc/delivery-method/push" "urn:ietf:rfc:8935"
endpoint_url
required
string <uri> <= 2048 characters

The target endpoint URL where the transmitter delivers the SET using HTTP POST requests

authorization_header
string or null <= 8192 characters

The HTTP Authorization header that is included for each HTTP POST request

string or Array of strings

The audience used in the SET. This value is set as aud in the claim.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

One of:

The audience used in the SET. This value is set as aud in the claim.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

string <uri>
events_delivered
Array of strings <uri>

The events (mapped by the array of event type URIs) that the transmitter actually delivers to the SSF Stream.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

events_supported
Array of strings <uri>

An array of event type URIs that the transmitter supports.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

format
string

The Subject Identifier format expected for any SET transmitted.

Value: "iss_sub"
iss
string

The issuer used in Security Event Tokens (SETs). This value is set as iss in the claim.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

min_verification_interval
integer or null

The minimum amount of time, in seconds, between two verification requests.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

stream_id
string

The ID of the SSF Stream configuration

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/ssf/stream
Request samples
Response samples

Update an SSF Stream
Early AccessIdentity Engine
OAuth 2.0: ssf.manage

Updates properties for an existing SSF Stream configuration.

If the stream_id isn't provided in the request body, the associated stream with the Client ID (through the request OAuth 2.0 access token) is updated.

Request
Request Body schema: application/json
required
events_requested
required
Array of strings <uri> <= 50 items

The events (mapped by the array of event type URIs) that the receiver wants to receive

required
object (Stream Configuration Delivery)

Contains information about the intended SET delivery method by the receiver

method
required
string

The delivery method that the transmitter uses for delivering a SET

Enum: "https://schemas.openid.net/secevent/risc/delivery-method/push" "urn:ietf:rfc:8935"
endpoint_url
required
string <uri> <= 2048 characters

The target endpoint URL where the transmitter delivers the SET using HTTP POST requests

authorization_header
string or null <= 8192 characters

The HTTP Authorization header that is included for each HTTP POST request

string or Array of strings

The audience used in the SET. This value is set as aud in the claim.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

One of:

The audience used in the SET. This value is set as aud in the claim.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

string <uri>
events_delivered
Array of strings <uri>

The events (mapped by the array of event type URIs) that the transmitter actually delivers to the SSF Stream.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

events_supported
Array of strings <uri>

An array of event type URIs that the transmitter supports.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

format
string

The Subject Identifier format expected for any SET transmitted.

Value: "iss_sub"
iss
string

The issuer used in Security Event Tokens (SETs). This value is set as iss in the claim.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

min_verification_interval
integer or null

The minimum amount of time, in seconds, between two verification requests.

A read-only parameter that is set by the transmitter. If this parameter is included in the request, the value must match the expected value from the transmitter.

stream_id
string

The ID of the SSF Stream configuration

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

patch/api/v1/ssf/stream
Request samples
Response samples

Delete an SSF Stream
Early AccessIdentity Engine
OAuth 2.0: ssf.manage

Deletes the specified SSF Stream.

If the stream_id is not provided in the query string, the associated stream with the Client ID (through the request OAuth 2.0 access token) is deleted. Otherwise, the SSF Stream with the stream_id is deleted, if found.

Request
query Parameters
stream_id
string

The ID of the specified SSF Stream configuration

Example: stream_id=esc1k235GIIztAuGK0g5
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/ssf/stream
Request samples
Response samples
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}