> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Access and Authentication

> Find your A2 API address and get a token for APIs that require authentication.

Ad and recommendation requests and event and log delivery don't need an access token. You only issue and use an access token to call APIs that manage ad operations data.

To request and render an ad and confirm that click events are collected, follow [Quick Start](https://docs.aiderx.io/development/en/quick-start.md). If you only send ad requests and events, you can skip issuing a token.

## API address

For both A2 On-Premise and A2 Cloud, use the API address provided for your deployment. In the examples, replace `your_a2_service` with that domain.

```
https://your_a2_service
```

Call the health check API to confirm the address.

```bash theme={null}
curl "https://your_a2_service/api/manager/health"
```

```json Response theme={null}
{"plane": "manager", "status": "ok", "db": "connected"}
```

## Authentication by API

Whether you need an access token depends on what the API is for.

| Purpose | API | Access token |
| - | - | - |
| Request ads and recommendations; send ad events such as impressions, clicks, and conversions, and user activity logs | Decision API | Not required |
| Manage ad operations data such as advertisers, campaigns, creatives, placements, and catalogs | Data Management API | Required |

The APIs for ad and recommendation requests and event and activity log delivery don't need an access token, so you can call them directly from a web page or app. Call the Data Management API from your server, with your access token in the `Authorization: Bearer <token>` header.

> [!WARNING]
>
> A token included in web or app code can be exposed.

## Issue an access token

Issue the access token in Ad Manager with an admin account.

**1. Sign in to Ad Manager**

Sign in to Ad Manager with an admin account.

**2. Go to Development Settings**

Open **Management > Settings** and go to the **Development Settings** section.

**3. Issue or copy the token**

If **Access Token** is empty, click the refresh icon to issue one. If a token already exists, click the copy icon to copy it. Clicking the refresh icon makes the existing token unusable, so be careful.

> [accordion] Get a login token for testing
>
> You can also get a login token with an account's email and password. A login token acts with that account's permissions and expires after 8 hours. Use it for testing or one-off tasks.
>
> The `access_token` value in the response is the login token. It is different from the access token issued in Development Settings.
>
> ```bash theme={null}
> curl -X POST "https://your_a2_service/api/auth/jwt/login" \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   --data-urlencode "username=dev@example.com" \
>   --data-urlencode "password=<password>"
> ```
>
> ```json Response theme={null}
> {"access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer"}
> ```

## Call an API with your token

Replace `<token>` with your token and read your account information to check that authentication works.

```bash theme={null}
curl "https://your_a2_service/api/users/me" \
  -H "Authorization: Bearer <token>"
```

On success, you get the account that issued the token.

```json Response (excerpt) theme={null}
{
  "id": "3f6c2a1e-8b7d-4c1a-9e2f-5d4b3a2c1b0a",
  "email": "a2-integration@example.com",
  "role": "admin",
  "is_active": true
}
```

A missing or invalid token returns `401`. If the account doesn't have permission to call the API, you get `403`.

## Regenerate the token

You don't need to manage an expiration date for the access token, and there is only one per system. If it leaks or needs replacing, regenerate it on the Ad Manager Development Settings screen.

The access token acts with the permissions of the admin account that issued it. If that account is deactivated or deleted, requests with the token fail, and changing the account's role or permissions can block some APIs. Before you remove the account or change its permissions, regenerate the token with another admin account and update your integrated systems.

You can also regenerate it through the API. The new token is in `access_token.access_token` in the response.

> [!WARNING]
>
> Regenerating the token makes the old token stop working immediately. Update every system that used it.

```bash theme={null}
curl -X POST "https://your_a2_service/api/manager/settings/access-token" \
  -H "Authorization: Bearer <token>"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.