# Authentication

Every request to the Envoke REST APIs is authenticated with HTTP Basic Auth: your API ID is the username and your API Key is the password. This article explains where to find them, what must be in place before they work, how API limits apply, and what the API returns when it refuses a request.

---

## Credentials

| Credential | Basic Auth role | Format |
|---|---|---|
| API ID | Username | 32 hexadecimal characters |
| API Key | Password | 32 characters, which can include `/`, `-`, `_`, `*`, and `?` |

The API ID and API Key belong to one Envoke account, and every request made with them reads and changes that account's data only. If your organisation has more than one Envoke account, each account has its own API ID and API Key.

There is one API Key per account. It is not tied to an Envoke user, and anyone who has it has full API access to the account, so keep it out of source control, browser code, and shared documents. Envoke support can replace a key; there is no way to replace it yourself.

The same credentials work for every API in this reference, on both `/v1` and `/v2`.

---

## Find Your API ID and API Key

1. In Envoke, open the settings menu and choose **Account settings**.
2. Choose the **Integrations** tab.
3. In the **API** section, choose **Reveal Credentials**. The `API_ID` line is your API ID and the `API_KEY` line is your API Key.

The API section is shown only to users who can manage the API. Other users see "Only administrators can view API connection details."

---

## Before Your Key Works

All of the following must be true. Until they are, requests are refused even with the correct API ID and API Key.

- **Your plan includes the API.** If it does not, the Integrations tab shows an **Upgrade your plan** link instead of the API section.
- **The API is enabled for your account.** If the Integrations tab shows an **Enable API** button, choose it. Enabling the API sets your account's limits to 1,000 requests a day and 3 requests a second (see [API Limits](#api-limits)) and shows the API section with your credentials. Until the API is enabled, every request returns `429` with `API access is not enabled for your account.`
- **Your account has a current key.** If the API section says "Please contact support in order to use the API" instead of offering **Reveal Credentials**, your account has an older key that Envoke support must replace before you can use the API.
- **Your account is active.** A closed or inactive account returns `403` (see [Error Responses](#error-responses)).

The Send API has one more prerequisite: the Transactional API preference on the same Integrations tab. See the [Send API overview](https://envoke-developers.pages.dev/v1/send/fields/#overview).

---

## Make a Request

Pass the API ID and API Key with curl's `-u` option, which sends them in an `Authorization: Basic` header. Keep the quotes: the key can contain characters your shell would otherwise interpret.

```bash
export API_ID="your API ID"
export API_KEY="your API Key"

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?limit=1"
```

Any other HTTP client works the same way: send the header `Authorization: Basic ` followed by the Base64 encoding of `API_ID:API_KEY`.

A `200` response confirms that the credentials work. This request returns a JSON array holding at most one tag, or `[]` if your account has no tags.

---

## API Limits

Every authenticated request counts towards your account's API limits. Enabling the API sets two limits:

| Limit | Default | Resets |
|---|---|---|
| Daily | 1,000 requests | At midnight Eastern time |
| Per second | 3 requests | At the start of each second |

The Integrations tab shows your daily limit, the number of requests counted so far today, and the per-second limit. To raise a limit, or to reset the daily count early, contact Envoke support.

- **What counts.** Each request that passes authentication counts once, whatever its result, including requests refused with `429` because a limit was exceeded. Requests refused with `401`, or with `403` because the account is not active, do not count.
- **Webhook deliveries count too.** Each event Envoke delivers to your webhook endpoints adds one to the same daily and per-second counts. Deliveries are never refused for being over a limit, but a high webhook volume can use up the daily limit and cause your own API requests to be refused with `429`.
- **Email alerts.** When your account reaches 80% of its daily limit, and again when it exceeds the limit, Envoke emails the account administrator who signed in most recently. Each alert is sent at most once a day.
- **No limit headers.** Responses carry no rate-limit headers. Track your own request rate, or check the usage on the Integrations tab.

When a request is refused with `429` for the per-second limit, wait a second and retry. When it is refused for the daily limit, every further request is refused until midnight Eastern time, unless Envoke support resets the count or raises the limit.

---

## Error Responses

### 401 — Invalid credentials

Returned when the `Authorization` header is missing, or the API ID and API Key do not match an Envoke account.

```json
{
  "success": false,
  "result_data": [],
  "result_text": "Invalid credentials"
}
```

The response carries a `WWW-Authenticate: Basic` header. Its `Content-Type` is `text/html`, although the body is JSON.

### 403 — Account not active

Returned when the API ID and API Key are correct but the account cannot use the API: it has been closed, or it is cancelled or suspended. The body is one of:

```json
{
  "success": false,
  "result_data": [],
  "result_text": "This account has been closed."
}
```

```json
{
  "success": false,
  "result_data": [],
  "result_text": "This account is not active."
}
```

Some endpoints also return `403` for reasons of their own, such as the Reports API on an account restricted from contact-level email activity; each is documented with its endpoint, for example [Contact Activity errors](https://envoke-developers.pages.dev/v2/reports/contacts/#errors).

### 429 — API not enabled or limit exceeded

When the API has not been enabled for the account:

```json
{
  "success": false,
  "result_data": [],
  "result_text": "API access is not enabled for your account."
}
```

When a limit is exceeded, `result_text` names the limit, `result_data.exceeded` is the period that was exceeded (`day` or `second`), and `result_data.limits` gives each of the account's limits with its current usage:

```json
{
  "success": false,
  "result_data": {
    "exceeded": "day",
    "limits": {
      "day": { "limit": 1000, "current_usage": 1001 },
      "second": { "limit": 3, "current_usage": 0 }
    }
  },
  "result_text": "Daily API limit of 1000 exceeded."
}
```

For the per-second limit, `result_text` is `Per second API limit of 3 exceeded.` and `exceeded` is `second`.

---

*Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.*

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*