Authentication & connections
There are two separate credentials in this integration.
| Credential | Purpose | Where to use it |
|---|---|---|
| Personal API token | Identifies you and limits the API operations you can call | Authorization: Bearer … header on API and MCP requests |
stel_token + stel_adowner | Gives the server access to your Telegram Ads session | Supplied explicitly by the extension's Connect or Replace action |
Request a personal API token from your workspace operator. Automated sign-up, Telemetr.io SSO and OAuth discovery are not available in this development release. Your analytics API key does not authenticate to this service.
Scope and ownership
| Scope | Access |
|---|---|
connections:read | List, inspect and check your connections |
connections:write | Create connections, replace cookies and disconnect |
ads:read | Read Telegram Ads data and validate a text-only preview |
mcp:read + ads:read | Use the hosted MCP endpoint |
Every connection belongs to the principal identified by the token. Requests for a connection belonging to somebody else return the same not-found response as a missing connection.
The extension uses a personal token with connection read/write access. An MCP client needs both mcp:read and ads:read for the selected connection. Scope restrictions are enforced by the service, not by a client-supplied owner ID.
Connection lifecycle
An active connection contains a validated Telegram session. If a read detects session expiry, replace the cookies. Disconnect removes the encrypted cookies and retains disconnected metadata.
Cookie replacement and disconnection use the current version returned by the connection API. A stale version returns CONNECTION_VERSION_CONFLICT; reload the connection before acting again. The extension handles this field for you.
The saved connection can expose several Telegram Ads accounts. Always select an accountId from that connection's account list. Do not infer it from a connection UUID or from the currently selected browser account.
Browser access
The public documentation and /health are accessible without authentication. API data routes require a bearer header; opening a data URL in a browser address bar does not add that header.
The development extension and this documentation origin are allowed browser origins. A different web app requires an explicit operator update to the Origin allowlist. Server-to-server clients should send the correct API URL and bearer token normally.
Keep tokens out of URLs and public screenshots. The extension keeps its personal token in session storage and does not store the Telegram cookie values in extension storage. Server-side connection cookies are encrypted at rest.