> ## 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.

# Authentication

> Credentials, base URLs, and error codes for each SideShift API.

Each SideShift API issues its own credential and has its own base path. They are not
interchangeable — a Connect key will not authenticate a Platform request.

All four share the host `https://app.sideshift.app`.

| API                                     | Base path       | Credential                | Header          |
| --------------------------------------- | --------------- | ------------------------- | --------------- |
| [Platform — API key](/platform/api-key) | `/api/v1`       | Company API key           | `x-api-key`     |
| [Platform — OAuth](/platform/oauth)     | `/api/oauth/v1` | OAuth 2.1 token           | `Authorization` |
| [Connect](/connect)                     | `/api/embed`    | `sk_live_…` / `sk_test_…` | `x-api-key`     |
| [Scraper](/scraper)                     | `/api/v1`       | `scrape_live_…`           | `x-api-key`     |

## Platform — API key

A key created in **Settings → Integrations**, sent on every request.

```http theme={null}
GET /api/v1/programs HTTP/1.1
Host: app.sideshift.app
x-api-key: YOUR_KEY
```

Platform access requires an active SideShift subscription. Requests from a company without
one return `402 { "error": "Active subscription required" }`.

<Note>
  The published API-key surface is read-oriented — 24 operations, of which 5 write
  (export posts, create a program invite, and create/send/void invoices). Restricted
  endpoints such as Jobs, Applicants, and payout execution are **not part of this spec**;
  they live in a separate Full Access spec available to allowlisted partner accounts.
</Note>

## Platform — OAuth 2.1

OAuth 2.1 authorization code flow with PKCE (S256). Access tokens are bound to a single
tenant (`company_id`) and carry only the scopes you request. Send them as
`Authorization: Bearer <token>`.

| Endpoint        | URL                                                |
| --------------- | -------------------------------------------------- |
| Discovery       | `/.well-known/oauth-authorization-server`          |
| Authorize       | `https://app.sideshift.app/api/oauth/v1/authorize` |
| Token / refresh | `https://app.sideshift.app/api/oauth/v1/token`     |

Scopes are granular and split read from write — for example `campaigns:read` and
`campaigns:write`, `payouts:read` and `payouts:write`. Request the narrowest set your
integration needs; `payouts:write` and `settings:write` are flagged sensitive in the spec
because they move money and change company configuration.

The full scope list is on the [OAuth reference](/platform/oauth).

## Connect

A key created in **Settings → Connect**, sent as `x-api-key`.

The key prefix selects the environment — `sk_test_…` routes to sandbox and `sk_live_…` to
production, against the same base URL. There is no separate sandbox host.

## Scraper

An independent key created in [Scraper → API Keys](https://app.sideshift.app/scraper),
sent as `x-api-key`.

1. Click **Create key**.
2. Copy it immediately — the full value is shown only once.

<Warning>
  Stored key previews in the dashboard are truncated and cannot be used to authenticate.
  If you lose a key, create a new one.
</Warning>

## Rate limits and errors

Platform API-key limits, returned on every response as `X-RateLimit-Limit`,
`X-RateLimit-Remaining`, and `X-RateLimit-Reset`:

* **100 requests per minute** per API key
* **400 requests per minute** for allowlisted partner accounts

Errors come back as `{ "error": "<message>" }`. Some endpoints add a `code`, such as
`LEAD_NOT_FOUND`.

| Status | Meaning                                      |
| ------ | -------------------------------------------- |
| `400`  | Invalid request                              |
| `401`  | Invalid or missing key                       |
| `402`  | No active subscription                       |
| `403`  | Restricted endpoint, or cross-company access |
| `404`  | Not found                                    |
| `429`  | Rate limited                                 |

<Warning>
  This error shape is specific to the Platform **API-key** surface. OAuth uses a structured
  envelope instead — `{ error: { code, message, requestId } }` — and quotes the `requestId`
  for support. See [Platform API](/platform).
</Warning>

Connect has its own per-endpoint limits — account creation 100/hour, token generation 30/min
per account, transfers 60/min, general 100/min — returning `429` with a `Retry-After` header.
See [Connect](/connect).

<Note>
  Scraper rate limits are documented in its own specification, which is currently being
  revised. That section will be added once the revision lands.
</Note>