# Signals connection reference
> Reference for connecting to Snowplow Signals: interface support by task, connection credentials, SDK client options and methods, and API and MCP endpoints.
> Source: https://docs.snowplow.io/docs/signals/connection/reference/
> Documentation index: https://docs.snowplow.io/llms.txt

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](/docs/signals/connection/).

## 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](https://console.snowplowanalytics.com) | ✅                     | ❌                   | ❌                          | Console login        |
| [Python SDK](#python-sdk)                                 | ✅                     | ✅                   | ✅                          | API key              |
| [Node.js SDK](#nodejs-sdk)                                | ❌                     | ✅                   | ❌                          | API key              |
| [Browser plugin](/docs/signals/applications/subscribe/)   | ❌                     | ❌                   | ✅                          | Signals API URL only |
| [Signals API](#signals-api-endpoints)                     | ✅                     | ✅                   | ✅                          | API key              |
| [Signals MCP server](#signals-mcp-server-endpoint)        | ❌                     | ✅                   | ❌                          | API key              |
| [Snowplow MCP server](/docs/ai/snowplow-mcp/)             | ✅                     | ✅                   | ❌                          | 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](/docs/account-management/) in Console | UUID                                               |
| API key ID      | A Snowplow API key ID                   | [Generated by you](/docs/account-management/) in Console | UUID                                               |
| Organization ID | Your Snowplow organization ID           | Console > **Signals** > **Overview**                     | UUID                                               |

### Python SDK

Package: [`snowplow-signals`](https://pypi.org/project/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`](https://www.npmjs.com/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](/docs/signals/applications/retrieve-attributes/) and [Retrieve agentic contexts](/docs/signals/applications/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](/docs/signals/connection/#signals-api) for the commands.

### Signals MCP server endpoint

The [Signals MCP server](/docs/signals/applications/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,
});
```

***