Authentication & tokens
InsurGrid integrations use two separate credentials, and mixing them up is the most common first-week mistake. This guide goes one level deeper than Get your API credentials — read that page first if you haven't set anything up yet.
New term — credential: a secret value (a token or key) that proves who's making a request. Anyone who has it can act as you, so it's handled like a password, not like configuration.
The two credentials, side by side
API token (management token)
You → InsurGrid
You're allowed to call the InsurGrid API.
Authorization: Bearer <token> header on every API request.
Signing secret
InsurGrid → you
A webhook POST genuinely came from InsurGrid.
Never sent anywhere. Stored on your server; used to check each webhook's signature.
They're not interchangeable. The API token authenticates outbound calls you make to https://api.insurgrid.com/v2. The signing secret authenticates inbound deliveries InsurGrid makes to your endpoint. If you find yourself trying to send the signing secret in a request header, stop — that's not what it's for.
Both live in the API section of your dashboard.
Using the API token
Every call to the InsurGrid API carries the token as a bearer header:
Authorization: Bearer <token>New term — bearer token: a secret string that acts like a password for API calls. Whoever "bears" (holds) it can call the API as you — so it's never put in front-end code, a public repo, or a URL, and it's never logged.
Node:
const res = await fetch("https://api.insurgrid.com/v2/forms", {
headers: { Authorization: `Bearer ${process.env.INSURGRID_API_TOKEN}` },
});Python:
Using the signing secret
The signing secret never travels over the network. You use it locally, on your server, to recompute the signature of an incoming webhook and compare it to the one InsurGrid sent. If a request came from InsurGrid, the two match; if it's spoofed, they don't.
The full walkthrough — with the exact HMAC computation in Node and Python — is in Verify a webhook signature.
⚠️ The signing secret is shown once, at creation time. Copy it immediately into a secrets manager or your environment config. If you lose it, you can regenerate it — but that invalidates the old one, so update your server in the same change.
Keep-secret hygiene
Store both credentials in environment variables or a secrets manager — never hard-code them in source.
Never expose either one in browser or front-end code. The API token lets someone call the API as you; the signing secret lets someone forge webhooks that look genuine.
Don't commit either to a repo, even a private one, and don't paste them into logs, tickets, or chat.
If a credential leaks, regenerate it in the API section right away.
Staging vs production
InsurGrid issues separate credentials per environment. Your staging API token and signing secret are different from your production ones.
Staging
Building and testing. Safe to break; no real customer data.
Production
Live traffic, once your integration works end to end in staging.
Build and verify everything against staging first, then switch to production credentials when you go live — see Get access for how environments map to the URLs you register.