# Shared Signals Connector

Shared Signals Framework receivers. Synqly signs a security signal as a Security Event Token (SET) and delivers it to the configured receiver. Products in this category accept signals but do not support querying them back out.

The Synqly Shared Signals connector makes Synqly a Shared Signals Framework
(SSF) **Transmitter**. You post a security signal to Synqly. Synqly signs the
signal as a Security Event Token (SET) and delivers it to your end customer's
identity provider.

## What you supply, and what Synqly supplies

You supply the **subject** and the **event**. Synqly supplies the signed
envelope: the `iss`, `aud`, `jti` and `iat` claims, and the `kid` header. A
mapping cannot set any of them, because Synqly's signing key vouches for the
signal.

Synqly does not translate OCSF into SET. Post a partial SET, or declare a
mapping that produces one. Attach the mapping to the `ssf_post_event`
operation. With no mapping declared, Synqly sends your payload unchanged.

## What a success response means

A success response means the receiver **accepted** the event. It does not mean
the receiver acted on it. The receiver's policies decide the action, and the
end customer confirms the action in their own logs. Some receivers accept an
event and then ignore it, for example when the subject does not match a user
in that org.

Synqly's validation is **structural only**. Synqly checks that the signal is a
well-formed Security Event Token. Synqly does not check that the event type is
one the receiver acts on, because you select the schema.

## Signing keys

Synqly generates an RSA signing key for each integration and publishes the
public half at a JWKS URL. Key material is never exportable. If you must hold
the private key, use the embedded product instead.

- The first key is generated when you create the integration.
- Keys rotate automatically. There is no rotation endpoint and no schedule to
configure.
- To revoke a key, delete its credential. **Revocation is immediate, and it is
not routine rotation.** It invalidates signals that are still in flight,
which is correct for a key you believe is compromised and wrong for
anything else. Synqly generates a replacement at once; the key set returns
503 with `Retry-After` while it generates.


⚠ The key lifetimes are deliberately conservative and are **not yet measured
against a live receiver**. Treat them as current behaviour, not as a
guarantee: a key signs for up to 24 hours, stays published for about 52 hours
after it is created, and the key set is served with `Cache-Control: max-age=3600`.

## Deployment prerequisites

**The JWKS URL and the discovery URL must be reachable from the public
internet by each end customer's identity provider, without authentication.**
The provider fetches both; it does not accept pasted key material. Neither
route takes a Synqly token, which is inherent to being a transmitter, so a
proxy that demands one in front of them breaks stream configuration. Meet
this during setup: if a URL is unreachable, the stream fails at the provider,
not at Synqly.

**They must be `https` URLs.** Synqly accepts an `http` deployment address,
for a deployment that is plaintext the whole way out, but an identity provider
will not fetch a key set over plaintext, so that latitude does not extend to
this connector. If a proxy terminates TLS in front of your deployment, this is
that proxy's `https` address, not the plaintext one behind it.

**The deployment declares the base URL that Synqly composes all of these
URLs from.** Synqly cannot determine its own externally reachable address, so
whoever runs the deployment supplies it with the `--api-ingress-url` flag,
which is the API's address and not the web UI's -- that one is
`--ingress-url`. It is not part of an integration's configuration: where
Synqly answers is a property of the deployment, and it is the same for every
integration on it.

On Synqly Cloud this is already set for your region. On an on-premise or
Synqly Embedded deployment, set it to the hostname at which your deployment is
reached from the public internet. Until it is set, this connector refuses to
send a signal or to report its URLs, because every value it would produce
points nowhere.

**If your deployment answers under a path, the discovery URL does not.** The
specification puts that document at the root of the host and your path after
the well-known segment rather than before it, so a deployment reached at
`https://gateway.example.com/synqly` publishes it at
`https://gateway.example.com/.well-known/ssf-configuration/synqly/v1/ssf/<integration-id>`.
Route that tree to Synqly as well; the Issuer and JWKS URLs stay under your
path as you would expect. Most deployments answer at the root of a hostname
and have nothing to do here.

⚠ **A change of hostname or load balancer breaks every configured stream**,
because each end customer's identity provider holds the old URLs. Treat the
base URL as a long-lived commitment.

## Reading the URLs back

Call the `ssf_get_transmitter_urls` operation with an integration token. It
returns three values and no key material:

- `issuer` -- the Issuer URL, which is also the `iss` claim of every token
Synqly signs for this integration.
- `jwks_url` -- where the public half of this integration's signing keys is
served.
- `well_known_url` -- the discovery URL, which serves this integration's
Transmitter Configuration Metadata: a document naming the other two and the
delivery method.


**You register one or the other, not all three.** A receiver that supports
discovery takes `well_known_url` alone and reads the rest out of the document
it finds there. A receiver that does not takes `issuer` and `jwks_url`. Okta
offers both and defaults to the discovery URL.

All three are composed when you read them rather than stored, so changing the
deployment's base URL changes them together, and the discovery document can
never disagree with the pair it names.

The discovery document is served whether or not a signing key exists yet,
which is the order a receiver works in: it reads the document to find the key
set URL, and the key set is where a warm-up appears, as a 503 with
`Retry-After`.

## API Reference

For full API documentation see the [Shared Signals API Reference](/api-reference/connectors/ssf).

To create an integration with the Shared Signals connector, use the [Create Integration API](/api-reference/management/integrations/integrations_create) endpoint, using one of the provider configs below.

## Supported Providers

- Okta Shared Signals (`ssf_okta`)


## Supported Operators by Provider

| API | Okta Shared Signals |
|  --- | --- |
| post_event | ✅ |
| get_transmitter_urls | ✅ |


## APIs with Filters

| API | Okta Shared Signals |