Skip to main content

REST API Overview

Authentication, account scoping, permissions, and response contracts for /api/v1

Table of Contents

REST API Overview

AffiliateBase exposes REST endpoints under /api/v1.

This overview covers authentication, account scoping, API-key permissions, and consistent response/error handling.

Base URL

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

Example:

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

Authentication

Supported auth formats (all /api/v1 endpoints):

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

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.
  • Session-authenticated requests may resolve Current.account, but API-key clients should always send account context explicitly.

Authorization Model

  • Session auth enforces account membership roles (owner, admin, member) per endpoint.
  • API-key auth enforces permission maps (resource/action), not membership roles.
  • If no permissions are provided when creating a key, the key defaults to full access ({ "all": true }).

Permission examples:

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

Common Query Patterns

  • Pagination: ?page=1&limit=25 (limit is capped at 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: { ... }
  • List responses: often include pagination metadata
  • Errors: structured JSON with error, code, and optional details

Pagination shape:

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

Error shape:

{
  "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)

Next steps