API key quickstart

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.

Building a product that connects other SideShift companies? Use the OAuth quickstart instead.

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.

Before you start

You need a SideShift company with an active subscription and owner/admin access (or API credential management permission). With explicit team scopes, use settings:read to inspect credentials and settings:write to create or revoke them. You can grant only permissions you currently have. See Team and integration permissions. 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 → Platform API & MCP → API keys and click Create key.

Name the workload, such as Internal reporting dashboard.
Choose Live. Use Test only for sandbox behavior; money-moving and external-side-effect writes are blocked.
Select only the scopes it needs. Choose campaigns:read for this guide.
For a parent agency, optionally enable Allow access to sub-accounts and choose a selected list or all current and future children. See Agency access.
Click Create key, then copy it immediately.

In the new design system, open Settings → API & MCP → API Keys and click Create API Key. That dialog creates a Live Platform key with the same scope and subaccount selections.

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:

curl -sS "https://app.sideshift.app/api/oauth/v1/campaigns?limit=25" \
  -H "x-api-key: $SIDESHIFT_API_KEY"

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();

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()

List endpoints return:

{
  "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. Each request intersects the saved scopes with the creator’s current company permissions. Removing the creator’s access stops the key; reducing access narrows it. Delegated child calls also check current access in that child. Read and Write are independent. 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 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

Key secrets cannot be recovered; scopes and subaccount delegation cannot be edited after creation. To rotate without downtime:

Create a second key with the required scopes.
Deploy the new key and verify a request succeeds.
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 invalid_api_key`	Check the key, revocation, and whether its creator still has company access. Send it in `x-api-key`, not as Bearer.
`403 insufficient_scope`	Check both the saved key scopes and the creator’s current permissions. Replace the key only if its saved selection is insufficient.
`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.

Platform API reference

Find current endpoints and the scope required for each operation.

Build for other users

Use OAuth 2.1 with PKCE when another company grants your app access.

​Before you start

​1. Create a scoped key

​2. Make your first request

​3. Use the full Platform API

​Rotate or revoke a key

​Common errors

Platform API reference

Build for other users

Before you start

1. Create a scoped key

2. Make your first request

3. Use the full Platform API

Rotate or revoke a key

Common errors