Authentication

Every request to the Product API carries a bearer token in the Authorization header. Tokens are issued in the dashboard, scoped to an organization or a project, and grant only the permissions you explicitly check off when you create them.

Two kinds of token

• Product API token — the full-feature token. Can read and write any surface of the Product API the scopes allow: audience, events, segments, campaigns, automations, direct SMS and — because the Ingest API is a subset of Product — contacts and events in any data source of the project.
• Datasource token — a narrower token minted for a single data source. Write-only against that data source. The right choice for CRM or e-commerce syncs that should not see anything else. See Ingest authentication.

Use the widest token only where the workload actually needs it. A reporting dashboard does not need PROJECT_AUDIENCE_WRITE; a CRM sync does not need any read scopes.

Getting a token

1. 1

   Open Project settings

   Sign in to the dashboard, pick the project that will own the token, and open Project settings → API tokens.

2. 2

   Pick the scopes

   Check only the scopes the integration needs — see the scope list in the Guide. Tokens are immutable once created; if you need a different scope later, mint a new token and rotate.

3. 3

   Copy the token and the project UID

   Both are needed for every call. The token is shown once; the project UID appears on the same page and does not change.

Sending the token

Preferred in every environment: the Authorization header. The token never appears in URLs, logs or browser history.

curl "https://api.instasent.com/v1/project/$PROJECT" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"

A missing, malformed or revoked token returns 401 Unauthorized. A token that is valid but lacks the scope for the endpoint returns 403 Forbidden.

Scopes recap

Three scopes cover most day-to-day integrations:

• PROJECT_AUDIENCE_READ + PROJECT_AUDIENCE_LIST + PROJECT_AUDIENCE_DATA_BASIC — segmentation and reporting dashboards.
• PROJECT_DATASOURCE_WRITE + PROJECT_AUDIENCE_WRITE — CRM / e-commerce syncs and automation backends.
• PROJECT_DIRECT_WRITE — triggering direct SMS from your application.

See the Guide for the full list, privacy levels and the scopes that require manual grant by Instasent.

Rotating a token

Tokens do not expire. Rotate them whenever a teammate leaves, whenever a secret might have been exposed, and at least once a year as a hygiene measure.

1. 1

   Issue the replacement

   Create a new token with the same scopes before revoking the old one. This keeps traffic flowing while you redeploy.

2. 2

   Roll it out

   Update your secrets store and redeploy every worker that calls the Product API.

3. 3

   Revoke the old token

   Once the replacement is live everywhere, delete the old token in the dashboard. Any request still using it will fail with 401.

What's next

• Rate limits — per-plan ceilings and the X-RateLimit-* headers.
• Errors — status codes and retry guidance.