API overview, hosts and 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.
On this page
| 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 |
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.
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 / | Our picks, in our order | pk_ |
| Publisher | The wall’s URL with ?uid= | A hosted wall for one user | None or ows_ |
| Advertiser | POST / | Reports a step a user completed | ak_ |
| Advertiser | POST / | Finds the tap behind a new install | ak_ |
| Network | GET /network-api/offers | Every offer your network can run | ak_ |
Full reference: Offer API, Top Offers Feed, Hosted Offerwall, advertiser events, 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.
| Key | Starts with | Where you make it | Lifetime |
|---|---|---|---|
| Publisher 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 | 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.
Publisher:
curl -G "https://affiliateos.xyz/publisher/offers" \
-d country=US -d platform=iOS \
-H "x-api-key: $AFFILIATEOS_KEY"Network:
curl -G "https://affiliateos.xyz/network-api/offers" \
-d country=US -d platform=ios \
-H "x-api-key: $AFFILIATEOS_KEY"Advertiser:
curl -X POST "https://affiliateos.xyz/v1/advertiser/events" \
-H "Authorization: Bearer $AFOS_ADVERTISER_KEY" \
-H "Content-Type: application/json" \
-d @event.jsonExample. Read the key from your server’s environment, never from source code.
| 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 |
| 403 | Network calls: the key is fine, but the account is restricted or still pending | Contact support |
Why an API key stopped working walks through each case, and Errors and rate limits covers every other error.
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 hold the same facts in one Markdown file per role.