Skip to main content
AffiliateBase
Features Pricing Compare Help
Log in Start for free

AffiliateBase REST API Overview

Learn AffiliateBase REST API authentication, account scoping, permissions, pagination, and response contracts under /api/v1.

Table of Contents

The AffiliateBase REST API under /api/v1 lets developers read or manage account-scoped affiliate program records such as affiliates, referrals, commissions, and payouts. This overview covers authentication, account scoping, API-key permissions, pagination, and response and error formats.

Base URL

  • Production: https://app.affiliatebase.io
  • Endpoint prefix: /api/v1

Example:

Terminal
curl "https://app.affiliatebase.io/api/v1/affiliates?account_id=<ACCOUNT_ID>&page=1&limit=25" \
  -H "Authorization: Bearer <API_KEY>"

Authentication

All /api/v1 endpoints accept these API key formats:

  1. Authorization: Bearer <API_KEY>
  2. Authorization: Basic <base64(API_KEY:)>
  3. X-Api-Key: <API_KEY>

Access tokens issued to AI connectors through OAuth are not accepted at /api/v1. They return 403 with the code FORBIDDEN regardless of their permissions, because they work only at the MCP endpoint. Create an API key in Settings -> API keys for REST access. See API Keys and REST API.

Account scoping

All /api/v1 endpoints require account context. Provide one of:

  1. ?account_id=<ACCOUNT_ID>
  2. X-Account-Id: <ACCOUNT_ID>

Notes:

  • API keys are account-scoped. API-key clients must always send X-Account-Id or account_id.
  • Signed-in dashboard sessions fall back to the account currently selected in the dashboard.

Authorization model

  • Session auth enforces account membership roles (owner, admin, member) per endpoint.
  • API-key auth enforces permission maps (resource/action), not membership roles.
  • Keys created in Settings -> API keys have full access ({ "all": true }).
  • POST/api/v1/api_keys#
    requires an explicit, non-empty permissions object. A request without one returns 422 with VALIDATION_ERROR.

Permission examples:

JSON
{ "all": true }
JSON
{
  "v1.affiliates.read": true,
  "v1.referrals.read": true,
  "v1.campaigns.write": false
}

Common query patterns

  • Pagination: ?page=1&limit=25 (default limit is 25; maximum is 100 on paginated routes)
  • Arrays: either repeated params (state[]=due&state[]=pending) or comma-delimited (state=due,pending)
  • Expansion: ?expand[]=campaign&expand[]=links or ?expand=campaign,links
  • Timestamps: endpoints that support updated_since/updated_until require ISO-8601 values

Response patterns

Most routes return:

  • Single object: the resource fields directly, not wrapped in data
  • List responses: a data array plus a pagination object on paginated routes
  • Errors: structured JSON with error, code, and optional details

Paginated list responses use this shape:

JSON
{
  "data": [],
  "pagination": {
    "previous_page": null,
    "current_page": 1,
    "next_page": 2,
    "count": 25,
    "limit": 25,
    "total_pages": 10,
    "total_count": 250
  }
}

Errors use this shape. details appears only on some errors:

JSON
{
  "error": "Account ID is required",
  "code": "MISSING_ACCOUNT_ID"
}

Common error codes:

  • MISSING_ACCOUNT_ID (400)
  • UNAUTHORIZED (401)
  • FORBIDDEN (403)
  • NOT_FOUND (404)
  • VALIDATION_ERROR (422)
  • INVALID_PARAMETER (400)
  • TOO_MANY_REQUESTS (429; see Rate limits)

An invalid updated_since or updated_until timestamp returns 422 with VALIDATION_ERROR.

Payout endpoints also return operation-specific 422 codes such as PAYOUT_EXECUTION_FAILED, PAYOUT_RUN_EXECUTION_FAILED, and PAYOUT_EXPORT_CREATE_FAILED. See the REST API endpoint reference for the full list.

Next steps

Esc