> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform API

> Run SideShift campaign operations programmatically — programs, contracts, payouts, and analytics.

Programs, contracts, payouts, analytics, and posts — the core SideShift product surface,
available two ways depending on how much access your integration needs.

<div className="ss-jump">
  <a href="#choose-how-to-authenticate">Choose auth</a>
  <a href="#the-practical-difference">Differences</a>
  <a href="#oauth-2-1">OAuth 2.1</a>
  <a href="#mcp-server">MCP server</a>
  <a href="#sandbox-and-sensitive-operations">Sandbox</a>
  <a href="#coverage">Coverage</a>
</div>

## Choose how to authenticate

<div className="ss-fork">
  <a className="ss-fork__card ss-fork__card--recommended" href="/platform/oauth">
    <div className="ss-fork__head">
      <h3 className="ss-fork__name">OAuth 2.1 & MCP</h3>
      <span className="ss-tile__badge">Recommended</span>
    </div>

    <p className="ss-fork__desc">
      Scoped read and write access across the full platform. Register an app, request only
      the capability scopes you need, and act on behalf of a tenant. Also exposed as an MCP
      server.
    </p>

    <span className="ss-fork__meta">262 operations · Bearer token</span>
  </a>

  <a className="ss-fork__card ss-fork__card--muted" href="/platform/api-key">
    <div className="ss-fork__head">
      <h3 className="ss-fork__name">API key</h3>
      <span className="ss-tile__badge ss-tile__badge--muted">Simpler</span>
    </div>

    <p className="ss-fork__desc">
      A header key from Settings → Integrations. Fastest way to start, but the surface is
      narrow and almost entirely read-only.
    </p>

    <span className="ss-fork__meta">24 operations · x-api-key</span>
  </a>
</div>

<Note>
  Skeleton page — the prose here is a first pass. Both references in the sidebar are
  generated from the production specifications and are accurate.
</Note>

## The practical difference

The two surfaces are not the same API with different credentials. The API-key surface is
**read-oriented**: of its 24 operations, 19 are `GET`. Only five write anything —

* `POST /posts/export`
* `POST /programs/{id}/invite`
* `POST /invoices`, `POST /invoices/{invoiceId}/send`, `POST /invoices/{invoiceId}/void`

If your integration needs to create a campaign, sign a contract, execute a payout, or send
a message, you need OAuth. If you are pulling analytics, posts, payouts, or creator data
into a dashboard or warehouse, the API key is enough and is quicker to set up.

They also behave differently on the wire — not just different credentials, but different
pagination, error shapes, and idempotency rules.

|             | API key                                                          | OAuth 2.1                                                                         |
| ----------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Base URL    | `/api/v1`                                                        | `/api/oauth/v1`                                                                   |
| Pagination  | `page` + `limit` (default 25, max 100) → `{ data, page, total }` | opaque `cursor` + `limit` (default 25, max 100) → `{ data, nextCursor, hasMore }` |
| Errors      | `{ "error": "message" }`                                         | `{ error: { code, message, requestId } }`                                         |
| Idempotency | Not specified                                                    | `Idempotency-Key` honored on POST/PATCH/PUT, **required** on money-moving writes  |
| Timestamps  | Unix milliseconds, e.g. `1634567890000`                          | —                                                                                 |

<Note>
  Agency (parent) accounts can pass `scope=agency` on the API key's analytics and posts
  endpoints to aggregate across the parent agency and every subaccount.
</Note>

## OAuth 2.1

Access is granted through a standard OAuth flow:

<Steps>
  <Step title="Register a client">
    Use Dynamic Client Registration to obtain a `client_id` — and, for confidential clients,
    a secret.
  </Step>

  <Step title="Request authorization">
    Use the authorization-code grant with PKCE (`S256`). The user sees a consent screen and
    picks the company (tenant) and scopes to grant.
  </Step>

  <Step title="Exchange the code">
    Trade the code at the token endpoint for a short-lived bearer access token and a refresh
    token.
  </Step>

  <Step title="Refresh">
    Use the refresh-token grant. Refresh tokens rotate on every use.
  </Step>
</Steps>

Every request is bound to the tenant and to the exact scopes the user granted, so an
integration can only do what it was authorized to do. Endpoint details are in the **OAuth
Registration**, **OAuth Authorization**, **OAuth Token**, and **OAuth Discovery** sections
of the reference. The protocol follows RFC 6749, 7009, 7591, 7592, 7636, 8414, 9068, and
9728\.

## MCP server

The same OAuth-scoped capabilities are exposed through a remote Model Context Protocol
server at `POST /api/mcp`, using the Streamable-HTTP transport. An AI agent can operate a
SideShift company through MCP tools instead of raw HTTP calls.

**Connecting a client.** Point any MCP client at `https://app.sideshift.app/api/mcp`. It
authenticates with the same OAuth 2.1 flow above — there is no MCP-specific auth scheme.
Tokens minted for MCP are multi-audience, so a single token works for both `/api/oauth/v1`
and `/api/mcp`. An unauthorized request gets a `401` with a `WWW-Authenticate` challenge
pointing at the RFC 9728 protected-resource metadata, so compliant clients can auto-discover
the authorization server.

**What you get.** Every capability scope maps to tools, mirroring the REST surface plus a
`whoami` tool. Read scopes expose read-only tools. Write and sensitive tools carry a
confirmation guardrail in their description. The claim-link capability is available as the
`create_quickpay_claim_link` tool.

## Sandbox and sensitive operations

Test and sandbox grants can exercise reads and safe writes, but requests that move money or
trigger outbound side-effects — payouts, sending invoices or messages, external re-scrapes —
are rejected.

Money-moving endpoints and campaign analytics-history validation/import requests require an
`Idempotency-Key`.

Sensitive MCP tools are rejected for sandbox and test grants, and can be disabled globally
with the `MCP_SAFE_MODE` server flag.

## Coverage

Campaigns and programs are the same concept; the OAuth spec names them campaigns, the
API-key spec names them programs.

| Area                                        | API key           | OAuth 2.1                     |
| ------------------------------------------- | ----------------- | ----------------------------- |
| Programs / Campaigns                        | Read              | Read & write                  |
| Posts                                       | Read, plus export | Read & write                  |
| Analytics                                   | Read              | Read                          |
| Payouts                                     | Read              | Read & write, incl. Quick-Pay |
| Invoices                                    | Read & write      | Read & write                  |
| Contracts                                   | Read              | Read & write                  |
| Creators & Discover                         | Read              | Read & write                  |
| Jobs, Applicants, Recruit                   | Not in this spec  | Yes                           |
| Messages & Conversations                    | No                | Yes                           |
| Wallet, Billing, Companies, Team            | No                | Yes                           |
| Booking, Disputes, Brand Verification       | No                | Yes                           |
| Agencies, Community, Integrations, Settings | No                | Yes                           |

The API-key spec exposes 8 tags. The OAuth spec exposes 38.

<Warning>
  Platform access requires an active SideShift subscription — requests from a company
  without one return `402`. Restricted endpoints (Jobs, Applicants, payout execution) are
  documented in a separate Full Access specification available to allowlisted partner
  accounts, and are not part of the API-key reference on this site. A non-allowlisted key
  calling them receives `403`.
</Warning>