Connecting & auth

Creating a client

Node.js
Python

import { FinnClient } from '@riseanalytics/finn-sdk';

const finn = new FinnClient({
  url: 'https://finn.example.com',
  apiKey: process.env.FINN_API_KEY,
});

from finn_sdk import FinnClient

finn = FinnClient(
    url="https://finn.example.com",
    api_key=os.environ["FINN_API_KEY"],
)

Constructing a client does not open a connection — it just holds config. Call connect() when you’re ready:

Node.js
Python

await finn.connect();     // opens the WebSocket and authenticates
// ... use the client ...
await finn.disconnect();  // closes it

await finn.connect()      # opens the WebSocket and authenticates
# ... use the client ...
await finn.disconnect()   # closes it

# Or as an async context manager (auto connect/disconnect):
async with FinnClient(url=url, api_key=key) as finn:
    ...

Options

Everything except url is optional. The Python client takes the same options as snake_case keyword arguments (e.g. api_key, get_api_key, session_id, system_prompt, timeout_ms).

Option (Node.js)	Python	Type	Default	Description
`url`	`url`	`str`	—	Required. Base URL of the Finn backend, e.g. `https://finn.example.com` or `wss://…`.
`apiKey`	`api_key`	`str`	—	Static API key, sent as the WebSocket handshake auth token.
`getApiKey`	`get_api_key`	`() -> str \| Awaitable[str]`	—	Alternative to `apiKey`: resolve the key at connect time (e.g. for rotation).
`path`	`path`	`str`	`'/ws'`	Socket.IO path on the backend.
`sessionId`	`session_id`	`str`	—	Resume a prior session.
`systemPrompt`	`system_prompt`	`str`	—	Client-level system-prompt default applied to new conversations. See System prompts.
`reconnection`	`reconnection`	`bool`	`true`	Auto-reconnect on a dropped socket.
`timeoutMs`	`timeout_ms`	`int`	`10000`	Connect timeout in milliseconds.

Authentication

Finn uses a single static API key. Provide it either directly or lazily:

Node.js
Python

// Direct
const finn = new FinnClient({ url, apiKey: 'your-key' });

// Resolved at connect time — handy for rotating secrets
const finn = new FinnClient({
  url,
  getApiKey: async () => await vault.read('finn/api-key'),
});

# Direct
finn = FinnClient(url=url, api_key="your-key")

# Resolved at connect time — handy for rotating secrets.
# get_api_key may be sync or async.
finn = FinnClient(
    url=url,
    get_api_key=lambda: vault.read("finn/api-key"),
)

If the key is missing or rejected, connect() raises a FinnError whose code is 'unauthorized', and the client emits an unauthorized event.

Lifecycle events

Subscribe with on(event, handler):

Node.js
Python

finn.on('unauthorized', () => console.error('API key rejected'));
finn.on('rateLimit', (info) => console.warn('rate limited', info));
finn.on('disconnect', (reason) => console.warn('disconnected:', reason));

finn.on("unauthorized", lambda *_: print("API key rejected"))
finn.on("rateLimit", lambda info: print("rate limited", info))
finn.on("disconnect", lambda reason: print("disconnected:", reason))

Event handlers are plain callbacks (not coroutines). The event names are the same in both languages.

Event	Payload	Fires when
`connected`	—	The session is established (after `connect()`).
`reconnect`	—	The socket reconnected after a drop.
`unauthorized`	—	The API key is missing or rejected.
`rateLimit`	`RateLimitInfo`	The backend signals a rate limit.
`disconnect`	`reason: string`	The socket drops (auto-reconnect may follow if enabled).