Connect to Snowplow Signals

You'll connect to Signals for one of two reasons:

• To define and manage configurations: create attribute groups, services, and interventions, and publish them to Signals. This is typically done by a data team, using Snowplow Console, the Python SDK, or the API.
• To consume calculated values in your application: retrieve attributes on demand, or subscribe to interventions. This is typically done in application code, using the SDKs, browser plugin, or API.

This table shows which interface supports which task:

Interface	Define configurations	Retrieve attributes	Subscribe to interventions
Snowplow Console	✅	❌	❌
Python SDK	✅	✅	✅
Node.js SDK	❌	✅	❌
Browser plugin	❌	❌	✅
Signals API	✅	✅	✅

Console doesn't require any connection setup: log in and navigate to the Signals section. If Signals isn't enabled for your organization yet, see Set up Signals.

For the SDKs, plugin, and API, you'll need connection credentials.

Connection credentials

To connect to Signals using the Signals SDKs or API, you will need four values. Use the Console Overview page to access them.

Value	Description	Where to get it	Format
Signals API URL	The API URL for your Signals deployment	Console > Signals > Overview	https://{{123abc}}.signals.snowplowanalytics.com
API key	A Snowplow API key	Generated by you in Console	UUID
API key ID	A Snowplow API key ID	Generated by you in Console	UUID
Organization ID	Your Snowplow organization ID	Console > Signals > Overview	UUID

Add these four tokens to your environment secrets.

Signals Python SDK

Use the Signals Python SDK to define attribute groups, services, and interventions via code. You can also retrieve calculated attributes and subscribe to interventions using this SDK.

To use the Python SDK, first choose where to store your Signals configurations. We recommend creating a new repository. The easiest way to use the SDK is within a Jupyter notebook.

Install the SDK into your environment:

bash

pip install snowplow-signals

Once installed, you can start to define configuration components. To test or publish your configuration, or retrieve calculated attributes or interventions from the Profiles Store, you'll need to connect to your Signals deployment.

Create a Signals object by passing in the required values:

python

from snowplow_signals import Signals

sp_signals = Signals(
    api_url=SIGNALS_DEPLOYED_URL,
    api_key=CONSOLE_API_KEY,
    api_key_id=CONSOLE_API_KEY_ID,
    org_id=ORG_ID,
)

The created Signals object has the following methods:

Method	Description
publish	Registers the provided objects with Signals
unpublish	Unpublishes objects from Signals
delete	Fully deletes objects from Signals (must unpublish first)
test	Tests an attribute group against the atomic events table
get_service_attributes	Retrieves attributes for a specific service from the Profiles Store
get_group_attributes	Retrieves attributes for a specific attribute group from the Profiles Store
get_attribute_group	Retrieves an attribute group from the Profiles Store
push_intervention	Push an intervention to subscribers for a set of attribute keys
pull_interventions	Open a streaming subscription of interventions for a set of attribute keys

To define configurations programmatically, check out the attribute groups, services, and interventions pages. The configuration workflow describes how publishing, versioning, unpublishing, and deletion fit together.

To consume calculated values in your application, see retrieve attributes and subscribe to interventions.

Signals Node.js SDK

Use the Node.js SDK to retrieve calculated attributes.

Install the SDK into your application:

bash

npm i @snowplow/signals-node
# or
yarn add @snowplow/signals-node
# or
pnpm i @snowplow/signals-node

Create a Signals object by passing in the required values:

typescript

import { Signals } from '@snowplow/signals-node';

const signals = new Signals({
  baseUrl: SIGNALS_DEPLOYED_URL,
  apiKey: CONSOLE_API_KEY,
  apiKeyId: CONSOLE_API_KEY_ID,
  organizationId: ORG_ID,
});

The created Signals object has the following methods:

Method	Description
getServiceAttributes	Retrieves attributes for a specific service from the Profiles Store
getGroupAttributes	Retrieves attributes for a specific attribute group from the Profiles Store
getBatchServiceAttributes	Retrieves attributes for multiple identifiers from a service

See retrieve attributes for usage examples.

Signals API

The Signals API allows you to directly configure and retrieve attributes and interventions. To access the full Swagger API documentation for your Signals deployment, use your Signals API URL followed by /docs/:

bash

{{API_URL}}/docs/

Your API documentation is linked in Console on the Overview page, under Configuration details.

Authenticate to the Signals API

The SDKs handle authentication for you. When you call the Signals API directly, each request must include a Bearer token in the Authorization header.

To obtain this token, exchange your Snowplow API key and key ID for a temporary access token using the Console Credentials API. The token is a JWT valid for 24 hours. See Account management for the full process, including how to create an API key.

First, exchange your API key and key ID for an access token:

bash

curl \
  --header 'X-API-Key-ID: <API_KEY_ID>' \
  --header 'X-API-Key: <API_KEY>' \
  https://console.snowplowanalytics.com/api/msc/v1/organizations/<ORGANIZATION_ID>/credentials/v3/token

This returns a JWT:

json

{ "accessToken": "<JWT>" }

Then use the JWT as a Bearer token in your Signals API requests:

bash

curl \
  --header 'Authorization: Bearer <JWT>' \
  {{API_URL}}/api/v1/registry/interventions

Signals Sandbox

This token exchange applies to Console deployments. For Signals Sandbox, use the Sandbox token from the Configuration details on the dashboard.