> For the complete documentation index, see [llms.txt](https://docs.insurgrid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurgrid.com/guides/authentication.md). # 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](/get-started/03-api-credentials.md) — 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 | Credential | Direction | Proves | Where it goes | | -------------------------------- | --------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- | | **API token** (management token) | You → InsurGrid | You're allowed to call the InsurGrid API. | `Authorization: Bearer ` 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 ``` > **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:** ```js const res = await fetch("https://api.insurgrid.com/v2/forms", { headers: { Authorization: `Bearer ${process.env.INSURGRID_API_TOKEN}` }, }); ``` **Python:** ```python import os, requests res = requests.get( "https://api.insurgrid.com/v2/forms", headers={"Authorization": f"Bearer {os.environ['INSURGRID_API_TOKEN']}"}, ) ``` ## 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](/guides/signing-verification.md). > ⚠️ **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. | Environment | Use it for | | -------------- | ---------------------------------------------------------------- | | **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](/get-started/02-get-access.md) for how environments map to the URLs you register. ## Related * [Get your API credentials](/get-started/03-api-credentials.md) * [Register your endpoint & choose an auth type](/guides/register-endpoint-auth-types.md) * [Verify a webhook signature](/guides/signing-verification.md) * [Idempotency keys](/guides/idempotency.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.insurgrid.com/guides/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.