Signals connection reference

This page lists the interfaces, credentials, client options, and methods for connecting to Signals. To set up a connection step by step, see Connect to Snowplow Signals.

Parameters

The SDKs, the Signals API, and the Signals MCP server use the same connection credentials. The browser plugin needs only the Signals API URL, and Console and the Snowplow MCP server use your Console login.

Interfaces

This table shows which interface supports which task:

Interface	Define configurations	Retrieve attributes	Subscribe to interventions	Credentials
Snowplow Console	✅	❌	❌	Console login
Python SDK	✅	✅	✅	API key
Node.js SDK	❌	✅	❌	API key
Browser plugin	❌	❌	✅	Signals API URL only
Signals API	✅	✅	✅	API key
Signals MCP server	❌	✅	❌	API key
Snowplow MCP server	✅	✅	❌	Console login

Console uses your Console login. The Snowplow MCP server authenticates with your Console account or a Console API key.

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. Add the values to your environment secrets.

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

Python SDK

Package: snowplow-signals on PyPI. The Signals constructor takes the connection credentials:

Name	Type	Required	Description
api_url	str	Required	The Signals API URL.
api_key	str	Required	The Snowplow API key.
api_key_id	str	Required	The Snowplow API key ID.
org_id	str	Required	The Snowplow organization ID.

Python SDK 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	Pushes an intervention to subscribers for a set of attribute keys
pull_interventions	Opens a streaming subscription of interventions for a set of attribute keys

Node.js SDK

Package: @snowplow/signals-node on npm. The Signals constructor takes one options object:

Name	Type	Required	Description
baseUrl	string	Required	The Signals API URL.
apiKey	string	Required	The Snowplow API key.
apiKeyId	string	Required	The Snowplow API key ID.
organizationId	string	Required	The Snowplow organization ID.

Node.js SDK methods

All methods are asynchronous and return a promise. This table describes version 0.4 of the SDK.

Method	Arguments	Returns
getServiceAttributes	{ name, attribute_key, identifier }	An object of attribute names and values for one identifier
getBatchServiceAttributes	{ name, attribute_key, identifiers }, where identifiers is a non-empty array	An object of attribute names, each with an array of values in the same order as identifiers
getGroupAttributes	{ name, version, attributes, attribute_key, identifier }, where attributes is a non-empty array of attribute names	An object of attribute names and values for one identifier
getAgenticContext	{ name, identifier, format }, where format is "json" (default) or "narrative"	An object with attribute_key, identifier, name, started_at_ms, events, and optional prompt and version; or a string for "narrative"

The attribute_key argument takes any attribute key name, such as domain_userid. The SDK also exports SnowplowStandardAttributeKeys with the four built-in keys: USER_ID, DOMAIN_USER_ID, DOMAIN_SESSION_ID, and NETWORK_USER_ID.

Retrieve attributes and Retrieve agentic contexts show each method in use.

Authentication and errors

The SDK exchanges your API key and key ID for an access token from Console on the first request, and reuses it until it expires. The constructor throws if baseUrl is missing, or if the API key, key ID, or organization ID is missing.

When a request fails, the method rejects with an Error whose message starts with [Signals] API error:, followed by the HTTP status and the response body. If the access token can't be fetched, the message is [Signals] Failed to fetch access token. The SDK doesn't set a request timeout or retry failed requests, so add them in your application if you need them.

Endpoints

All endpoints are relative to your Signals API URL, shown here as {{API_URL}}.

Signals API endpoints

Endpoint	Description
{{API_URL}}/docs/	Swagger documentation for your deployment. Console also links to it from Overview > Configuration details.
{{API_URL}}/api/v1/...	The Signals API. Requests need an Authorization: Bearer <JWT> header.

To get the JWT, exchange your API key and key ID at the Console Credentials API, https://console.snowplowanalytics.com/api/msc/v1/organizations/<ORGANIZATION_ID>/credentials/v3/token, sending them in the X-API-Key-ID and X-API-Key headers. The token is valid for 24 hours. See Connect to Snowplow Signals for the commands.

Signals MCP server endpoint

The Signals MCP server serves calculated attributes and agentic contexts to an agent in your application as read-only tools. It uses streamable HTTP at:

bash

{{API_URL}}/mcp

It takes the API key and key ID directly, in the X-API-Key-Id and X-API-Key headers, so there's no token exchange.

Example

A Python client and a Node.js client created from the same environment variables:

Python

python

import os
from snowplow_signals import Signals

sp_signals = Signals(
    api_url=os.environ["SIGNALS_API_URL"],
    api_key=os.environ["SNOWPLOW_API_KEY"],
    api_key_id=os.environ["SNOWPLOW_API_KEY_ID"],
    org_id=os.environ["SNOWPLOW_ORG_ID"],
)

Node.js

typescript

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

const signals = new Signals({
  baseUrl: process.env.SIGNALS_API_URL,
  apiKey: process.env.SNOWPLOW_API_KEY,
  apiKeyId: process.env.SNOWPLOW_API_KEY_ID,
  organizationId: process.env.SNOWPLOW_ORG_ID,
});