API Authentication

Signing in to the dashboard

Every screen under the dashboard is protected by Clerk. You sign in with the email address on your account, and Clerk sets a session cookie in your browser. Marketing pages, the blog, the glossary, the tools and these docs stay public and are served without an auth check, which is why they load without a session.

The first time you sign in, Coldread creates your organisation, your user record and a 14 day free trial. If somebody invited you, your Clerk account is linked to the user record they created for you instead. An invite has to be claimed from a verified email address within seven days, otherwise it is refused and you are told to ask an admin to re-invite you.

How the application talks to the server

The dashboard calls the server through tRPC at /api/trpc. Those calls carry your Clerk session cookie, and the server resolves that cookie to your user, your organisation and your role on every request. There is no token you can copy out of the browser and reuse, and this endpoint is not documented as a public interface. Treat it as internal: the procedure names and payload shapes change with the product.

Two endpoints are deliberately open. The health checks under /api/health report database reachability and the deployed commit, and the Inngest endpoint at /api/inngest is called by the background job runner rather than by you.

Roles

Authentication tells Coldread who you are. Your role decides what you can do once you are in. Accounts carry one of four roles: owner, admin, manager or member. Whoever signs the organisation up becomes the owner. An invite carries whichever role the person sending it picks, and it defaults to member. Only an owner can hand out the owner role. The server checks the caller role on the request itself rather than in the browser, so hiding a button is never the only thing standing between a member and an admin action.

Webhook credentials

Inbound webhooks authenticate differently to the dashboard. Your Ringover webhook URL ends in an integration ID that is unique to your account, and that ID is the credential. Anyone holding the URL can post call events to your organisation, so treat it like a password: do not paste it into a ticket, a screenshot or a public repository. If it leaks, contact support and the integration can be deactivated.

When a webhook secret is stored against an integration, Coldread verifies an HMAC signature on the raw request body and rejects anything that does not match with a 401. Ringover does not sign its webhooks, so for Ringover integrations that check is skipped and the attempt is logged with the calling IP address instead. The endpoint also rate limits each integration to 120 requests per minute and answers 429 above that.

Billing events are different again. Stripe webhooks are verified against a shared signing secret before anything is read, and an event without a valid stripe-signature header is rejected with a 400.

Credentials you store with us

Provider credentials that you save in Settings, including integration API keys and webhook secrets, are encrypted before they are written to the database and decrypted only when a request needs them. Coldread never displays a stored secret back to you in full.

Not yet available

• Personal or organisation API keys, and a screen to create or revoke them
• Bearer token authentication for a public REST API
• OAuth apps, scopes and third party authorisation flows
• Service accounts and machine to machine credentials

If you need programmatic access, the API reference page explains the early access programme. Tell us which data you want to read and we will factor it into the design.