# Authentication and keys

> Every request sends an API key as a bearer token. Sandbox keys (`pads_test_`) return sample ads for free; live keys (`pads_live_`) read the platforms and use credits.

Base URL: `https://api.publicadsapi.com` · Auth: `authorization: Bearer <key>` · Web version: https://publicadsapi.com/docs/authentication

## Send the key

Every request:

```http
GET /v1/meta/ads?q=running+shoes HTTP/1.1
Host: api.publicadsapi.com
Authorization: Bearer $PADS_API_KEY
```

No header, or one that is not `Bearer <key>`, is `401 UNAUTHENTICATED`. A key that is not ours or has been revoked is `401 INVALID_KEY`. Neither uses credits.

## Sandbox and live keys

|  | Sandbox key | Live key |
| --- | --- | --- |
| Starts with | `pads_test_` | `pads_live_` |
| Answers with | Sample ads from made-up advertisers | The platform's library, read as the call runs |
| Credits | Never | 1 a page with ads or an ad found (LinkedIn 2) |
| Speed | At once | Usually 2 to 15 seconds, at most 60 |
| Rate limit | None | 5 to 50 requests a second, by plan: [Rate limits](https://publicadsapi.com/docs/rate-limits.md) |
| Shown | Any time on the dashboard | Once, when you create it |

Both kinds take the same requests and answer in the same shapes, so code built against the sandbox works live by changing the key.

## What the sandbox returns

- Each platform has a few sample ads with every field filled the way that platform fills it: Meta's EU reach, Google's text read from an image, TikTok's reach range, LinkedIn's payer.
- Pages hold 3 ads, so you can test paging with `next_cursor`. Meta's `active` and `format`, and Google's `format`, filter the samples; other filters are checked and echoed in `query` but return the same ads.
- Every id a sandbox search returns works with `GET /v1/ads/{id}`. Any other id is `404 AD_NOT_FOUND`.
- These searches answer as a platform sometimes does: `q=empty`, `q=blocked`, `q=timeout`, `q=changed` (also as `company` or a `domain`'s first part). For one ad, the ids `meta_blocked`, `google_blocked`, `tiktok_blocked`, `linkedin_blocked` and the same with `_timeout` and `_changed`. See [Test your error handling](https://publicadsapi.com/docs/quickstart.md#test-queries).

## Create, store and revoke keys

- Create and revoke keys on [Keys](https://publicadsapi.com/app/keys). A revoked key stops working at once.
- Keep a key in an environment variable such as `PADS_API_KEY` and call the API from your server. A key in a web page or an app can be read by anyone who has it.
- A live key is shown once. Lost one? Create another and revoke the old one.
- Use one key per app or environment, so you can see each one's calls on the dashboard and revoke one without the others.

> An AI agent with no key can get a sandbox key, then a live key with free credits, without a person signing up: see [Agents](https://publicadsapi.com/docs/agents.md).

See also: [Quickstart](https://publicadsapi.com/docs/quickstart.md) · [Search overview](https://publicadsapi.com/docs/api/search.md)