# Authentication

The Product API authenticates each request with a bearer token carrying specific scopes. Tokens are issued per organization or per project in the dashboard.

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](/ingest-api/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. Open Project settings

Sign in to the [dashboard](https://dashboard.instasent.com), pick the project that will own the token, and open **Project settings** → **API tokens**.

#### 2. Pick the scopes

Check only the scopes the integration needs — see the [scope list in the Guide](/product-api/guide#tokens-and-scopes). Tokens are immutable once created; if you need a different scope later, mint a new token and rotate.

#### 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.

> **Warning**: Treat tokens as production secrets. Keep them in an environment variable or a secrets manager; never commit them to the repo or embed them in client-side code. `PROJECT_AUDIENCE_DATA_FULL` tokens in particular carry PII access and should live in your most restricted vault.

## Sending the token

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

```bash
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](/product-api/guide#tokens-and-scopes) 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. Issue the replacement

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

#### 2. Roll it out

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

#### 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](/product-api/rate-limits)** — per-plan ceilings and the `X-RateLimit-*` headers.
- **[Errors](/product-api/errors)** — status codes and retry guidance.