# Authentication

> Authenticate with bearer keys, run a first test request, and resolve common authentication failures.

> Authenticate Kommon Poll API requests with bearer keys and verify access before building deeper integrations.

Every API request must include a Kommon Poll API key in the `Authorization` header.

```text
Authorization: Bearer YOUR_KOMMON_POLL_API_KEY
```

Use HTTPS for every request.

Do not put the API key in the URL or query string.

---

## 1. First Authentication Test

Use `GET /v4/list` as the first test because it requires authentication but does not require an `aid`.

```text
GET https://api.kommonpoll.com/v4/list
```

Example:

```bash
curl https://api.kommonpoll.com/v4/list \
  -H "Authorization: Bearer YOUR_KOMMON_POLL_API_KEY"
```

A successful response confirms that the key is valid and can access authorized Kommon Poll data.

If the expected saved search is not visible, confirm the team selected when the key was created.

---

## 2. Use The Returned aid

After `GET /v4/list` succeeds, choose the required saved search and copy its `aid`.

Use that value with `GET /v4/search`:

```text
GET https://api.kommonpoll.com/v4/search?aid=<AID>
```

---

## 3. Authentication Error Guidance

| Situation | Developer action |
| --- | --- |
| `Authorization` header is missing | Add `Authorization: Bearer <API key>`. |
| Key is invalid | Check that the full key was copied correctly. |
| Key was revoked | Create or use an active replacement key. |
| Key has expired, if expiry is configured | Generate or request a new key. |
| API Access is not enabled for the team or package | Use a team or package with API Access enabled, or contact Kommon Poll. |
| Saved search is not accessible | Confirm the `aid` belongs to the team associated with the API key. |

---

## 4. Security Rules

- Keep keys server-side.
- Prefer environment variables or a secrets manager.
- Redact the `Authorization` header from logs.
- Do not expose keys in browser JavaScript.
- Do not commit keys to Git.
- Use one key per integration and environment.
- Revoke exposed or unused keys immediately.