Skip to main content

For AI agents: a Markdown version of this page is at https://docs.snowplow.io/docs/signals/connection.md. The index of all documentation pages is at https://docs.snowplow.io/llms.txt, and the index for this section is at https://docs.snowplow.io/docs/signals/llms.txt.

Connect to Snowplow Signals

You connect to Signals for one of two reasons: to define and manage configurations, such as attribute groups, services, and interventions, or to consume calculated values in your application. A data team usually does the first with Console or the Python SDK. Application code does the second with the SDKs, the browser plugin, the API, or the Signals MCP server.

Console needs no connection setup: log in and go to the Signals section. The Snowplow MCP server, which lets your own coding agent manage Signals for you, authenticates with your Console account rather than with Signals credentials. Install it, with the Snowplow skills, using npx plugins add snowplow/skills.

This page covers connecting from code. For the full list of interfaces and what each supports, the client constructor options, and the SDK methods, see the Signals connection reference.

Before you begin​

You'll need:

  • Signals enabled for your organization. If it isn't, see Set up Signals.
  • Permission to create API keys in Console. See Account management.
  • Python 3, or Node.js, depending on the SDK you use

Choose your interface:

  • To define configurations in code: use the Python SDK. We recommend keeping your configurations in a new repository. A Jupyter notebook is the easiest place to start.
  • To retrieve attributes in a Node.js application: use the Node.js SDK.
  • To subscribe to interventions in the browser: use the browser plugin.
  • From any other language, or over plain HTTP: use the Signals API.
  • From an AI agent in your application: use the Signals MCP server.

Steps​

These steps connect with the Python or Node.js SDK. The code tabs remember your choice.

Get your connection credentials​

The SDKs, Signals API, and Signals MCP server use the same four values. The browser plugin needs only your Signals API URL, because the subscription endpoint doesn't authenticate. Find the Signals API URL and organization ID in Console under Signals > Overview, and create an API key to get the API key and its ID. Signals has two API key permissions: View for reading attributes and agentic contexts, and Edit for also creating and publishing configuration. Give an application that only reads attributes a key with View. The connection credentials reference lists the format of each.

Add the four values to your environment secrets. Keep them on the server: don't commit them or send them to the browser.

Install the SDK​

bash
pip install snowplow-signals

To call the Signals API directly, skip this step and go to Signals API.

Create a Signals client​

Create a Signals object with your connection credentials:

python
from snowplow_signals import Signals

sp_signals = Signals(
    api_url=SIGNALS_API_URL,
    api_key=SNOWPLOW_API_KEY,
    api_key_id=SNOWPLOW_API_KEY_ID,
    org_id=SNOWPLOW_ORG_ID,
)

Verify the connection​

Retrieve attributes from a published service. Replace my_service with one of your services, and the identifier with an attribute key value that has events, such as your own domain_userid:

python
sp_signals.get_service_attributes(
    name="my_service",
    attribute_key="domain_userid",
    identifier="218e8926-3858-431d-b2ed-66da03a1cbe5",
)

A response with attribute values, even empty ones, means the connection works. If you don't have a service yet, follow the quickstart tutorial to create one.

Next, define configurations with attribute groups, services, and interventions, or consume them with retrieve attributes and subscribe to interventions.

Signals API​

The SDKs handle authentication for you. When you call the Signals API directly, exchange your API key for a token first, then send it with each request.

Get an access token​

Exchange your API key and key ID for an access token, using the Console Credentials API:

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, valid for 24 hours:

json
{ "accessToken": "<JWT>" }

Account management describes the full process, including how to create an API key.

Call the API​

Send the JWT as a Bearer token in the Authorization header:

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

A list of interventions, even an empty one, means the connection works. The Signals API reference shows where to find the full API documentation for your deployment.

To connect, define attributes, and act on interventions from Python end to end, follow the Python tracking and Signals tutorial.

Was this page helpful?