# Authentication and API keys

> Every call carries an API key issued to your affiliate account, and names your campaign and affiliate.

## API keys

An API key belongs to your **affiliate account**. ICON issues keys; each key can carry its own [rate limits](https://developers.iconroute.io/rate-limits/) and an expiry date, and can be revoked at any time.

- **Where to find them:** your ICON contact issues and rotates your keys.
- **Keep keys on your server.** The API is server to server. Never put a key in a web page or an app.
- **One key per integration** makes rotation and troubleshooting easier. Ask for a new key before you revoke the old one.

## Sending the key

Send the key in the `Authorization` header:

```http
POST /api/v1/engine/search HTTP/1.1
Host: iconroute.io
Authorization: Bearer <your API key>
Content-Type: application/json
```

`X-API-Key: <your API key>` is accepted too. Prefer a header: a key in a URL ends up in logs.

## Campaign and affiliate on every call

The key says who you are; each search and submit also says **which campaign** it is for:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `icon_campaign_id` | string | required (search + submit) | ICON campaign ID (UUID) of the campaign this request is for. Required on every search and every submit: ICON never picks a campaign for you. |
| `icon_affiliate_id` | string | required (search + submit) | Your ICON affiliate ID (UUID). Required on every search and every submit, and must be the affiliate your API key belongs to. ICON records the affiliate from the key; this value is only checked against it. |

Your ICON contact gives you your affiliate id and your campaign ids. A campaign determines which offers a search covers and how your payout is set.

## When authentication fails

| HTTP | code | status | reason | When |
| --- | --- | --- | --- | --- |
| 401 | `AUTH_REQUIRED` | invalid | Missing API key | No API key was sent. |
| 401 | `AUTH_INVALID` | invalid | Invalid API key | ICON does not know the key, or it was revoked or has expired. |
| 403 | `FORBIDDEN` | invalid | Not permitted | The campaign, offer or lead is not yours, or the request is not allowed for this key. |

None of these is retryable as is: fix the key or the ids first.