# Authentication

The Ingest API authenticates each request with a bearer token scoped to a datasource. Product API tokens with the right scopes also work.

Every request to the Ingest API carries a bearer token in the `Authorization` header. Two flavours of token are accepted:

- **Datasource token** — issued per datasource from the dashboard. Can only read and write that datasource. The right choice for CRM, e-commerce or product-event integrations that should not see anything else.
- **Product API token** — a broader token that also works here as long as it carries the Ingest scopes. Convenient when a single backend drives both APIs.

Scope defaults to the datasource that minted the token; there is no way to widen it at request time.

## Getting a datasource token

#### 1. Open the datasource

In the [dashboard](https://dashboard.instasent.com), open the project and navigate to **Datasources** → pick the API datasource you want to write to, or create a new one with type **API**.

#### 2. Issue the token

Under **Credentials**, click **Generate token**. Copy the value straight away — it is shown once.

#### 3. Note the URL parts

The datasource page also shows the `project` and `datasource` identifiers that go in the URL:

```
https://api.instasent.com/v1/project/{project}/datasource/{datasource}/stream/...
```

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

## Sending the token

```bash
curl "https://api.instasent.com/v1/project/$PROJECT/datasource/$DATASOURCE/stream" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"
```

A missing, malformed or revoked token returns `401 Unauthorized`. Mismatched project/datasource ids return `404 Not Found`.

## 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 in the dashboard **before** revoking the old one. This keeps traffic flowing while you redeploy.

#### 2. Roll it out

Update your secrets store and redeploy the workers that call the 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](/ingest-api/rate-limits)** — per-endpoint ceilings and the `X-RateLimit-*` headers.
- **[Errors](/ingest-api/errors)** — status codes and partial-success shape.