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

# API key quickstart

> Create a scoped Platform API key and call SideShift for your own company in minutes.

Use a Platform API key when a script, scheduled job, backend service, or internal dashboard
calls SideShift for **your own company**. It is the shortest setup: create one scoped key and
send it with each request. There is no OAuth redirect, consent screen, or token exchange.

<Note>
  Building a product that connects other SideShift companies? Use the [OAuth
  quickstart](/quickstart) instead.
</Note>

<Warning>
  This guide uses a current `sspk_…` key with `/api/oauth/v1`. Older `sk_live_…`
  Platform keys call the deprecated `/api/v1` API and must not be used for new
  work.
</Warning>

## Before you start

You need a SideShift company with an active subscription and owner/admin access (or API
credential management permission). Keep the key on a trusted server; never put it in browser
JavaScript, a mobile app, source control, or logs.

## 1. Create a scoped key

Open [Settings → OAuth & MCP → API keys](https://app.sideshift.app/settings?tab=oauth\&oauthTab=keys)
and click **Create key**.

1. Name the workload, such as `Internal reporting dashboard`.
2. Choose **Live**. Use **Test** only for sandbox behavior; money-moving and external-side-effect
   writes are blocked.
3. Select only the scopes it needs. Choose `campaigns:read` for this guide.
4. Click **Create key**, then copy it immediately.

```bash theme={"system"}
export SIDESHIFT_API_KEY="sspk_live_..."
```

The complete key is shown once. SideShift stores only its hash, so a lost key cannot be
recovered—create a replacement and revoke the old one.

## 2. Make your first request

Every current Platform resource endpoint supports the key through `x-api-key`:

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -sS "https://app.sideshift.app/api/oauth/v1/campaigns?limit=25" \
    -H "x-api-key: $SIDESHIFT_API_KEY"
  ```

  ```js Node.js theme={"system"}
  const response = await fetch(
    "https://app.sideshift.app/api/oauth/v1/campaigns?limit=25",
    { headers: { "x-api-key": process.env.SIDESHIFT_API_KEY } },
  );

  const result = await response.json();
  ```

  ```python Python theme={"system"}
  import os
  import requests

  response = requests.get(
      "https://app.sideshift.app/api/oauth/v1/campaigns",
      params={"limit": 25},
      headers={"x-api-key": os.environ["SIDESHIFT_API_KEY"]},
  )

  result = response.json()
  ```
</CodeGroup>

List endpoints return:

```json theme={"system"}
{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}
```

An empty `data` array is successful when the company has no campaigns.

## 3. Use the full Platform API

The key works on the same `/api/oauth/v1/*` resource operations as an OAuth access token.
The selected scopes decide which operations it can call. For example:

| Goal                       | Scope             |
| -------------------------- | ----------------- |
| Read campaigns             | `campaigns:read`  |
| Create or update campaigns | `campaigns:write` |
| Read posts and metrics     | `posts:read`      |
| Read wallet information    | `wallet:read`     |

Open an operation in the [Platform API reference](/platform) to see its required scope.
Send **either** `x-api-key` **or** `Authorization: Bearer …` on a request, never both.

For POST, PUT, and PATCH requests, send an `Idempotency-Key`. It is required on money-moving
operations and prevents a retry from running the same change twice.

## Rotate or revoke a key

Keys cannot be recovered or expanded after creation. To rotate without downtime:

1. Create a second key with the required scopes.
2. Deploy the new key and verify a request succeeds.
3. Revoke the old key.

Revocation is immediate. Keep separate keys for separate workloads so you can rotate or revoke
one integration without interrupting another.

## Common errors

| Error                       | What to check                                                                     |
| --------------------------- | --------------------------------------------------------------------------------- |
| `401 unauthorized`          | The key is missing, malformed, or revoked. Send it in `x-api-key`, not as Bearer. |
| `403 insufficient_scope`    | Create a replacement key that includes the operation's required scope.            |
| `402 subscription_required` | The company needs an active subscription for protected resources.                 |
| `429 rate_limited`          | Wait for `Retry-After`, then retry with backoff.                                  |

Every resource error includes a `requestId`; include it when contacting SideShift support.

<CardGroup cols={2}>
  <Card title="Platform API reference" icon="briefcase-business" href="/platform">
    Find current endpoints and the scope required for each operation.
  </Card>

  <Card title="Build for other users" icon="users" href="/quickstart">
    Use OAuth 2.1 with PKCE when another company grants your app access.
  </Card>
</CardGroup>