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 
application/json
{}
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 
application/json
{}
Response samples 
application/json
{}
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 
application/json
{}
Response samples 
application/json
{}
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": [ ]
}