OAuth quickstart

This guide takes you from no credentials to a working Platform API request using OAuth 2.1 with PKCE. You will request the read-only campaigns:read scope, so the first token cannot change anything.

Only calling the API for your own company?

Create a scoped Platform API key instead. There is no callback URL, browser redirect, consent screen, or token exchange.

Building with Connect or the Scraper API? Those products have separate credentials and setup guides.

The API-key Platform API at /api/v1 is legacy and deprecated. It is not maintained and must not be used for new integrations. Existing integrations should plan to migrate to the OAuth API at /api/oauth/v1.

Before you start

You need:

A SideShift account and a company with an active subscription
A callback URL in your application
curl and openssl for the commands below

For this local example, the callback URL is http://127.0.0.1:3000/oauth/callback. Redirect URIs must use HTTPS in production; HTTP is allowed only for localhost, 127.0.0.1, [::1], and explicitly supported native callbacks. Userinfo, fragments, and wildcard bind addresses are rejected. Authorization matches the registered callback exactly, except a native HTTP loopback callback may vary only the port (RFC 8252 §7.3) — so the value must otherwise be identical in every step. This quickstart uses a public client with no client secret. PKCE protects the authorization code, while your backend must still keep access tokens, refresh tokens, and the registration access token private.

Optional: discover the endpoints instead of hard-coding them

SideShift publishes the two standard discovery documents at the domain root, so a client can resolve every endpoint at runtime rather than pinning the paths below.

curl -s https://app.sideshift.app/.well-known/oauth-authorization-server

{
  "issuer": "https://app.sideshift.app",
  "authorization_endpoint": "https://app.sideshift.app/api/oauth/v1/authorize",
  "token_endpoint": "https://app.sideshift.app/api/oauth/v1/token",
  "registration_endpoint": "https://app.sideshift.app/api/oauth/v1/register",
  "revocation_endpoint": "https://app.sideshift.app/api/oauth/v1/revoke",
  "jwks_uri": "https://app.sideshift.app/api/oauth/v1/jwks",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "code_challenge_methods_supported": ["S256"],
  "authorization_response_iss_parameter_supported": true
}

This is authorization-server metadata (RFC 8414). code_challenge_methods_supported confirms S256 is the only PKCE method, and authorization_response_iss_parameter_supported means the authorize redirect carries an iss parameter per RFC 9207 that you should check against issuer.The companion document is protected-resource metadata (RFC 9728):

curl -s https://app.sideshift.app/.well-known/oauth-protected-resource

{
  "resource": "https://app.sideshift.app/api/oauth/v1",
  "authorization_servers": ["https://app.sideshift.app"],
  "bearer_methods_supported": ["header"]
}

resource is the canonical resource identifier and the audience your access tokens are bound to. Both documents also list every supported scope.

1. Register your application

Register once to get a client_id. This example asks only to read campaigns and includes the refresh_token grant so the integration can stay connected.

curl -sS -X POST https://app.sideshift.app/api/oauth/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My SideShift integration",
    "redirect_uris": ["http://127.0.0.1:3000/oauth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "campaigns:read",
    "token_endpoint_auth_method": "none"
  }'

The response starts like this:

{
  "client_id": "oauthc_8f1c2e...",
  "registration_access_token": "rat_9a8b7c...",
  "registration_client_uri": "https://app.sideshift.app/api/oauth/v1/clients/oauthc_8f1c2e...",
  "redirect_uris": ["http://127.0.0.1:3000/oauth/callback"],
  "scope": "campaigns:read"
}

Copy the returned values:

export SIDESHIFT_CLIENT_ID="oauthc_8f1c2e..."
export SIDESHIFT_REGISTRATION_TOKEN="rat_9a8b7c..."

The registration_access_token is shown only once. Store it like a password; it can update or delete your OAuth client. It is not the token used to call the Platform API.

2. Send the user to SideShift

First, create a one-time PKCE verifier, its SHA-256 challenge, and a random state value:

export SIDESHIFT_CODE_VERIFIER="$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')"
export SIDESHIFT_CODE_CHALLENGE="$(printf '%s' "$SIDESHIFT_CODE_VERIFIER" \
  | openssl dgst -binary -sha256 \
  | openssl base64 | tr '+/' '-_' | tr -d '=')"
export SIDESHIFT_STATE="$(openssl rand -hex 16)"

Build the authorization URL for the callback and scope registered above. The callback and scope are already URL-encoded in this example; if you change either value, URL-encode the replacement too.

export SIDESHIFT_AUTHORIZE_URL="https://app.sideshift.app/api/oauth/v1/authorize?response_type=code&client_id=${SIDESHIFT_CLIENT_ID}&redirect_uri=http%3A%2F%2F127.0.0.1%3A3000%2Foauth%2Fcallback&scope=campaigns%3Aread&state=${SIDESHIFT_STATE}&code_challenge=${SIDESHIFT_CODE_CHALLENGE}&code_challenge_method=S256"

echo "$SIDESHIFT_AUTHORIZE_URL"

Open that URL in a browser. The user signs in to SideShift, chooses the company to connect, reviews the requested scope, and approves access. SideShift then redirects to your callback:

http://127.0.0.1:3000/oauth/callback?code=ac_4f2b...&state=...&iss=https://app.sideshift.app

Your callback must verify that:

state exactly matches $SIDESHIFT_STATE
iss is exactly https://app.sideshift.app

If no local server is running yet, the page may fail to load, but you can still copy code from the browser’s address bar for this manual test.

3. Exchange the code for tokens

Authorization codes are short-lived and single-use. Copy the code from the callback and exchange it from your backend with the same callback URL and PKCE verifier:

export SIDESHIFT_CODE="ac_4f2b..."

curl -sS -X POST https://app.sideshift.app/api/oauth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${SIDESHIFT_CODE}" \
  --data-urlencode "redirect_uri=http://127.0.0.1:3000/oauth/callback" \
  --data-urlencode "code_verifier=${SIDESHIFT_CODE_VERIFIER}" \
  --data-urlencode "client_id=${SIDESHIFT_CLIENT_ID}"

You receive a one-hour access token and a refresh token:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "campaigns:read",
  "refresh_token": "rt_9f8e..."
}

Copy both tokens into your server-side environment for the next steps:

export SIDESHIFT_ACCESS_TOKEN="eyJhbGciOi..."
export SIDESHIFT_REFRESH_TOKEN="rt_9f8e..."

4. Make your first API request

Send the access token as a bearer token:

curl -sS "https://app.sideshift.app/api/oauth/v1/campaigns?limit=25" \
  -H "Authorization: Bearer $SIDESHIFT_ACCESS_TOKEN"

const response = await fetch(
  "https://app.sideshift.app/api/oauth/v1/campaigns?limit=25",
  {
    headers: {
      Authorization: `Bearer ${process.env.SIDESHIFT_ACCESS_TOKEN}`,
    },
  },
);

const result = await response.json();

import os
import requests

response = requests.get(
    "https://app.sideshift.app/api/oauth/v1/campaigns",
    params={"limit": 25},
    headers={
        "Authorization": f"Bearer {os.environ['SIDESHIFT_ACCESS_TOKEN']}"
    },
)

result = response.json()

List endpoints return a cursor-paginated response:

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

An empty data array is a successful result when the connected company has no campaigns.

Connecting an agency parent? If the user granted direct sub-account access during consent, add X-Act-As-Company: CHILD_COMPANY_ID to run one request against that child. Do not use undocumented companyId, client, or similar query parameters as tenant selectors. See Agency sub-account requests for complete examples.

5. Refresh the connection

When the access token expires, exchange the refresh token for a new token pair:

curl -sS -X POST https://app.sideshift.app/api/oauth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${SIDESHIFT_REFRESH_TOKEN}" \
  --data-urlencode "client_id=${SIDESHIFT_CLIENT_ID}"

Refresh tokens rotate and are single-use. Atomically replace the old refresh token with the new one from every successful response. Reusing an old refresh token revokes the token family.

Common errors

Error	What to check
`invalid_redirect_uri`	The callback URL is missing or does not match a registered value (a native loopback HTTP callback may vary only the port).
`invalid_grant`	The code may be expired, already used, or paired with the wrong PKCE verifier.
`401 unauthorized`	The access token is missing, invalid, or expired. Refresh it and retry.
`402 subscription_required`	The company selected during consent needs an active subscription.
`403 insufficient_scope`	Check the token, client registration, consent, and the user’s current company permissions. For new access, register the scope and obtain fresh consent from someone who can grant it.

OAuth protected resource errors include a requestId. OAuth registration, authorization, and token endpoints instead use { error, error_description }. Include requestId when it is present and you contact SideShift support.

Before going live

Use an HTTPS callback URL and compare it by exact string; a native loopback HTTP callback is the only exception, and may vary only the port.
Store tokens and the registration access token in a secrets manager, never client-side code.
Request only the scopes your integration needs.
Verify state and iss before exchanging the authorization code.
Persist each rotated refresh token before discarding the previous one.

Platform API

Browse capabilities, scopes, and the OAuth reference.

Authentication

Compare credentials, base URLs, and error formats.

MCP server

Use the same OAuth grant with an AI agent.

Overview

Only calling the API for your own company?

Before you start

1. Register your application

2. Send the user to SideShift

3. Exchange the code for tokens

4. Make your first API request

5. Refresh the connection

Common errors

Before going live

Next

Platform API

Authentication

MCP server

Only calling the API for your own company?

​Before you start

​1. Register your application

​2. Send the user to SideShift

​3. Exchange the code for tokens

​4. Make your first API request

​5. Refresh the connection

​Common errors

​Before going live

​Next

Platform API

Authentication

MCP server

Before you start

1. Register your application

2. Send the user to SideShift

3. Exchange the code for tokens

4. Make your first API request

5. Refresh the connection

Common errors

Before going live

Next