# Authentication

The impact.com REST API authenticates requests using [HTTP Basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme). Each API access token consists of two values:

| Credential      | Purpose                                                              | Equivalent                  |
| --------------- | -------------------------------------------------------------------- | --------------------------- |
| **Account SID** | Uniquely identifies your token. Used as the HTTP Basic **username**. | Similar to a public API key |
| **Auth Token**  | The secret credential. Used as the HTTP Basic **password**.          | Similar to a secret API key |

Send the pair Base64-encoded in the `Authorization` header:

```
Authorization: Basic base64(AccountSID:AuthToken)
```

{% hint style="warning" %}
**Legacy tokens**

Tokens created before April 2025 are considered legacy tokens. You can continue using them, but they only offer read/write and read-only permission levels. To get finer-grained scope control, upgrade your legacy token or create a new access token. See [**Manage legacy tokens**](https://impact-1.gitbook.io/developer-portal/cEUQw2AQihKjONZAjPEy/rest-apis/create-an-api-key#manage-legacy-tokens) on the Create an API Key page.
{% endhint %}

All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure) (port 443). Calls made over plain HTTP will fail. Requests with missing or incorrect credentials return a `401` status code.

All API requests are scoped to your account type:

{% tabs %}
{% tab title="Brand" %}
As a Brand, your API base path is:

`https://api.impact.com/Advertisers/{AccountSID}/...`
{% endtab %}

{% tab title="Partner" %}
As a Partner, your API base path is:

`https://api.impact.com/MediaPartners/{AccountSID}/...`
{% endtab %}

{% tab title="Agency" %}
As an Agency, your API base path is:

`https://api.impact.com/Agencies/{AccountSID}/...`
{% endtab %}
{% endtabs %}

#### Create an API access token

Mint your credentials in [**impact.com**](https://app.impact.com/) → ![](/spaces/RnLJYNhGbpDCQOrCFmiI/files/KbRKpL2RdufOGukQobJB) **\[User profile] → Settings → Technical → API** → **Create Access Token**.

For the full UI walkthrough — including scope toggles, API version pinning, rotations, duplication, disables, deletes, and legacy migration — see [**Create an API Key**](https://impact-1.gitbook.io/developer-portal/cEUQw2AQihKjONZAjPEy/rest-apis/create-an-api-key).

{% hint style="info" %}
**New to impact.com?** Start with a token that has read-only scopes so scripts can't accidentally mutate production objects. Promote to separate tokens per environment (dev / staging / prod) with narrowly tailored scopes when you're ready to ship.
{% endhint %}

#### Store credentials securely

Never hardcode secrets in repositories. Store them in a secrets vault or in encrypted environment variables — never in source control or shared chats.

```bash
export IMPACT_SID="YOUR_ACCOUNT_SID"
export IMPACT_TOKEN="YOUR_AUTH_TOKEN"
```

#### Make an authenticated request

The examples below call the **Campaigns** endpoint with a `GET` request as a smoke test.

{% tabs %}
{% tab title="Brand" %}

```bash
curl --get \
  "https://api.impact.com/Advertisers/${IMPACT_SID}/Campaigns" \
  -u "${IMPACT_SID}:${IMPACT_TOKEN}" \
  -H "Accept: application/json"
```

```python
import os
import requests
from requests.auth import HTTPBasicAuth

sid = os.environ["IMPACT_SID"]
tok = os.environ["IMPACT_TOKEN"]
url = f"https://api.impact.com/Advertisers/{sid}/Campaigns"
r = requests.get(url, auth=HTTPBasicAuth(sid, tok), headers={"Accept": "application/json"})
print(r.status_code)
```

{% endtab %}

{% tab title="Partner" %}

```bash
curl --get \
  "https://api.impact.com/MediaPartners/${IMPACT_SID}/Campaigns" \
  -u "${IMPACT_SID}:${IMPACT_TOKEN}" \
  -H "Accept: application/json"
```

```python
import os
import requests
from requests.auth import HTTPBasicAuth

sid = os.environ["IMPACT_SID"]
tok = os.environ["IMPACT_TOKEN"]
url = f"https://api.impact.com/MediaPartners/{sid}/Campaigns"
r = requests.get(url, auth=HTTPBasicAuth(sid, tok), headers={"Accept": "application/json"})
print(r.status_code)
```

{% endtab %}

{% tab title="Agency" %}

```bash
curl --get \
  "https://api.impact.com/Agencies/${IMPACT_SID}/Campaigns" \
  -u "${IMPACT_SID}:${IMPACT_TOKEN}" \
  -H "Accept: application/json"
```

```python
import os
import requests
from requests.auth import HTTPBasicAuth

sid = os.environ["IMPACT_SID"]
tok = os.environ["IMPACT_TOKEN"]
url = f"https://api.impact.com/Agencies/{sid}/Campaigns"
r = requests.get(url, auth=HTTPBasicAuth(sid, tok), headers={"Accept": "application/json"})
print(r.status_code)
```

{% endtab %}
{% endtabs %}

#### Interpret the response

* **`2xx`** — success.
* **`401`** — bad or missing SID/Auth Token pair.
* **`403`** — credentials authenticated, but the persona path or token scopes block the resource. Double-check `Advertisers` / `MediaPartners` / `Agencies` and the token's scope toggles.
* **`429`** — slow down. Add exponential backoff with jitter in scripts and agents.

#### Protect your keys

Anyone with your Auth Token can make API calls on your behalf, up to the scopes granted. Follow these practices:

* **Use scoped tokens** instead of full-access tokens — grant only the permissions the integration actually needs.
* **Create separate tokens** for each integration, service, or environment (dev / staging / prod) so you can revoke one without affecting others.
* **Store credentials** in a secrets vault or encrypted environment variables. Never commit them to source code, configuration files, or version control.
* **Reset tokens** when team members leave or change roles.
* **Disable unused tokens** rather than leaving them active — you can re-enable them later if needed.
* **Don't share credentials** over email, chat, or other unencrypted channels.

#### Coming soon

OAuth 2.0 Authorization Code + PKCE flows for apps operating on behalf of many customers. Documentation will publish alongside developer onboarding once available.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://integrations.impact.com/agency-v3/readme/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.