> AffiliateOS Help Center. Index of every article for AI tools: https://www.affiliateos.ai/help/llms.txt

# API overview, hosts and authentication

Developer docs · For everyone · Updated 30 October 2026
Web version: https://www.affiliateos.ai/help/developers/api-overview-hosts-authentication

Every API call goes to `https://affiliateos.xyz` over HTTPS. Publishers and networks send their key in the `x-api-key` header; advertisers send theirs as `Authorization: Bearer`. Keys belong on your server, never in an app or a browser.

## Hosts

| Host (HTTPS) | What it's for |
|---|---|
| `affiliateos.xyz` | Every API call: offers, advertiser events, install matching |
| `offerwall.affiliateos.xyz` | The Hosted Offerwall, opened at `/w/` plus your wall's app ID |
| `app.affiliateos.xyz` | The dashboard you sign in to. Not an API. |
| Your own server | Where we send [postbacks](https://www.affiliateos.ai/glossary#postback) |

Use these hosts exactly. There is no separate `api.` subdomain. Tracking links come ready-made in each offer's `trackingUrl`: put your user's own ID in place of `{SUB_ID}` (and the device's advertising ID in place of `{DEVICE_ID}` when you have it), and leave the rest of the link as it is.

## Which API does what

Publishers and networks send the key in `x-api-key`, advertisers as `Authorization: Bearer`, and a signed wall link carries a signature made with `ows_` instead of a key.

| You are | Call | What it does | Key |
|---|---|---|---|
| Publisher | `GET /publisher/offers` | Every offer you can run, at your payout | `pk_` |
| Publisher | `GET /publisher/offers?segment=top` | Our picks, in our order | `pk_` |
| Publisher | The wall's URL with `?uid=` | A hosted wall for one user | None or `ows_` |
| Advertiser | `POST /v1/advertiser/events` | Reports a step a user completed | `ak_` |
| Advertiser | `POST /v1/advertiser/match-install` | Finds the tap behind a new install | `ak_` |
| Network | `GET /network-api/offers` | Every offer your network can run | `ak_` |

Full reference: [Offer API](https://www.affiliateos.ai/help/developers#offer-api), [Top Offers Feed](https://www.affiliateos.ai/help/developers#top-offers-feed), [Hosted Offerwall](https://www.affiliateos.ai/help/developers#offerwall), [advertiser events](https://www.affiliateos.ai/help/developers#advertiser-events), [Network API](https://www.affiliateos.ai/help/developers#network-api).

Offer lists come back as JSON, with the offers in `data.offers` and paging details in `data.pagination`. The Offer API returns every offer in one response unless you send `page` or `per_page` (then 50 to a page by default). The Network API pages by default, 50 to a page: keep asking while `has_more_pages` is true.

## Keys

| Key | Starts with | Where you make it | Lifetime |
|---|---|---|---|
| Publisher [API key](https://www.affiliateos.ai/glossary#api-key) | `pk_` | **My Profile**, then **API Keys**, then **Generate Key**. Owners and admins only. | Until you revoke it. Up to five at a time. |
| Network API key | `ak_` | **Workspace settings**, then **API Keys**, then **Generate Key** | 90 days by default. The **Expires** column shows the date. |
| Advertiser API key | `ak_` | **Mint API key** on a campaign, or **API keys**, then **Mint new key** | Until you revoke it |
| [Postback secret](https://www.affiliateos.ai/glossary#postback-secret) | `ps_` | Publishers: **Postbacks**, then **Create postback secret**. Networks: **Workspace settings**, then **Generate Webhook Secret**. | Until you replace or revoke it |
| Offerwall app secret | `ows_` | Only for walls set to signed launches | Keep it on your server |

Every key and secret you make in the dashboard is shown once, when you make it. Store it before you close the page.

> **Network keys and advertiser keys both start with ak_.** They are not interchangeable. A network key reads offers with `x-api-key`; an advertiser key sends events as a bearer token. Label each one where you store it.

## Send the key

Publisher:

```bash
curl -G "https://affiliateos.xyz/publisher/offers" \
  -d country=US -d platform=iOS \
  -H "x-api-key: $AFFILIATEOS_KEY"
```

Network:

```bash
curl -G "https://affiliateos.xyz/network-api/offers" \
  -d country=US -d platform=ios \
  -H "x-api-key: $AFFILIATEOS_KEY"
```

Advertiser:

```bash
curl -X POST "https://affiliateos.xyz/v1/advertiser/events" \
  -H "Authorization: Bearer $AFOS_ADVERTISER_KEY" \
  -H "Content-Type: application/json" \
  -d @event.json
```

Example. Read the key from your server's environment, never from source code.

## When the key is the problem

| Response | What it means | What to do |
|---|---|---|
| 401 `Missing x-api-key header` | No key reached us on a network call | Send the header named exactly `x-api-key` |
| 401 `Invalid or expired API key` | The key is wrong, revoked or past its date | Check the whole key was copied. Networks: check **Expires**. |
| 401 `Invalid API key` | An advertiser key that is wrong or revoked | Mint a new key and update your server |
| 401 `Partner account is not active` | A publisher account that is restricted | [Contact support](https://www.affiliateos.ai/contact?topic=support) |
| 403 | Network calls: the key is fine, but the account is restricted or still pending | [Contact support](https://www.affiliateos.ai/contact?topic=support) |

[Why an API key stopped working](https://www.affiliateos.ai/help/account/api-key-stopped-working) walks through each case, and [Errors and rate limits](https://www.affiliateos.ai/help/developers/errors-and-rate-limits) covers every other error.

## Rotate without downtime

Make the new key, deploy it, check a call succeeds, then revoke or remove the old one. Publishers can hold up to five keys, so there's room, and one key per environment means revoking a staging key never stops production. A network account holds one key unless we raise its limit: check **Used** in the key list.

Email us before you rotate and we'll allow a second key, or remove the old key and generate the new one in the same sitting.

For a coding assistant, the [AI context files](https://www.affiliateos.ai/help/developers#ai-context) hold the same facts in one Markdown file per role.