Authentication
Which credential each host takes: a Synpath API key for Synpath's hosted services, an access token for your own server's trading routes.
Three credentials exist, and they are never interchangeable. Each is issued by a different party for a different door.
| Credential | Issued by | Sent to | Variable |
|---|---|---|---|
| Venue credentials | Kalshi, Polymarket, Polymarket US | Never sent to any Synpath host. Read by your self-hosted server (synpath serve) from its environment | KALSHI_*, POLYMARKET_*, POLYMARKET_US_* |
| Access token | Your self-hosted server (synpath serve) | Your server's /trading routes and its events socket | SYNPATH_ACCESS_TOKEN |
| Synpath API key | api2.synpath.dev | Synpath's hosted services: matching at api.synpath.dev, historical data at api2.synpath.dev | SYNPATH_API_KEY |
Your server: market data
No authentication. Market data is public on every venue, and the server binds to 127.0.0.1 unless told otherwise. To expose it beyond your machine, put a proxy with TLS and your own auth in front.
Your server: trading
Every /trading request carries an access token as a bearer. On the machine the server runs on you never type it: your self-hosted server makes one on first start and leaves it in ~/.synpath/servers.json, readable by you only, where synpath.Client(server=...) and the TypeScript client find it. A server bound to a network address prints the token once instead; callers pass it.
curl "http://127.0.0.1:8000/trading/me" \
-H "Authorization: Bearer $SYNPATH_ACCESS_TOKEN"A missing or unknown token answers 401. A token that exists but lacks the permission a route needs answers 403 with the permission named.
Permissions
A grant is (user, account, permission). The account is venue:name, one set of venue credentials, or * for every account. Nothing is implied by another permission. An order on a bucket needs trade on every member venue.
| Permission | Allows |
|---|---|
view | Orders, fills, positions, balances, P&L, fair values, risk rules, status, the events socket |
trade | Place, amend and cancel orders; set fair values; halt and resume |
manage_credentials | Replace the risk rules; issue and revoke tokens |
manage_members | Grants, and the audit log |
Issuing tokens
The first token is the owner's, made by your self-hosted server on a new control database. Another one is issued through POST /keys by a token that holds manage_credentials, for example one per machine, so each can be revoked alone. A token carries the permissions of the user it is issued to. The secret is shown once and stored only as a hash, so a stolen database cannot be used to trade.
synpath bootstrap --control synpath-control.db # another owner token, shown onceEvery grant and token change is written to an append-only audit log with the actor and the request, readable at GET /audit.
Synpath's hosted services
Cross-venue matching at api.synpath.dev and historical data at api2.synpath.dev take a Synpath API key as a bearer, Authorization: Bearer $SYNPATH_API_KEY. Create one with synpath login, then synpath keys create; see Authentication.