Authentication

All requests (REST and WebSocket) require a Bearer API token.

Provide the Token

Send the token via the Authorization header:

Authorization: Bearer YOUR_TOKEN

Example request:

curl -H "Authorization: Bearer YOUR_TOKEN" https://developers.counttogether.app/v1/counters

Token Scope

A token grants access only to counters that belong to (or are shared with) the token's owner. There is no concept of per-endpoint scopes yet.

Failure Modes

Missing header → 401 Unauthorized (no body or generic JSON error)
Invalid / unknown token → 401 Unauthorized

WebSocket

Include the same Authorization: Bearer ... header when upgrading the connection:

wscat -c wss://developers.counttogether.app/v1/ws -H "Authorization: Bearer YOUR_TOKEN"

If the header is missing or invalid, the server rejects the upgrade with 401 or closes the socket immediately.

Token Rotation

When you rotate a token, existing WebSocket sessions using the old token will continue until disconnected; subsequent HTTP/WebSocket connections must use the new token.

Best Practices

Store tokens securely (environment variables or a secrets manager)
Never embed tokens in client-side code or public repositories

Last modified: 01 October 2025