# Authentication

The Transactional API authenticates each request with a bearer token. Create it in the dashboard, send it in the Authorization header, and rotate it when it leaks.

Every request to the Transactional API carries a token. Tokens are issued in the dashboard, scoped per project, and passed either in the `Authorization` header (recommended) or as a query-string parameter (convenient for quick tests).

## Getting a token

Sign in to the [Instasent dashboard](https://dashboard.instasent.com), open **API tokens** and create an `api_sms` token for the project that will send the traffic. Copy the value straight away — it is shown once.

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

### In the `Authorization` header

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

```bash
curl https://api.instasent.com/transactional/v1/sms \
  -H "Authorization: Bearer $INSTASENT_TOKEN"
```

### As a query-string parameter

Convenient for one-off checks from a browser or a copy-pasted curl. Only use it from trusted shells — URLs are logged by proxies and CDNs.

```bash
curl "https://api.instasent.com/transactional/v1/sms?access_token=$INSTASENT_TOKEN"
```

## Rotating a token

Tokens do not expire. Rotate them whenever a member of the team 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 `api_sms` token in the dashboard **before** revoking the old one. This keeps traffic flowing while you redeploy.

#### 2. Roll the new token 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 Unauthorized`.

## What's next

- **[Rate limits](/transactional-api/http/rate-limits)** — how many requests per minute and what the `X-RateLimit-*` headers tell you.
- **[Errors](/transactional-api/http/errors)** — status codes returned by the API and how to retry safely.