POST /v1/projects/:projectId/social/oauth-url

Create an OAuth authorization URL for TikTok or Instagram. The end-customer opens it in a top-level browser tab, consents on the platform's domain, and is redirected back to a returnUrl you control - not to Layers.

You pass returnUrl per call. It must match an allowlist on your API key; anything else is rejected with RETURN_URL_NOT_ALLOWED. Layers never re-hosts the consent page, and the URL cannot be framed (TikTok and Instagram block their domains from iframes by ToS). Your UI opens it in a new tab or redirects the user to it directly.

Request bodies are strict — sending an unknown field returns 422 VALIDATION with the offending key in details.issues[]. Don't rely on Layers silently dropping fields it doesn't recognize.

Setting up your returnUrl allowlist

Every API key has an allowlist of domains that returnUrl is checked against at call time. The allowlist is stored on the key itself and lives independently of platform OAuth — it's a Layers-side guardrail, not a TikTok or Instagram setting.

How matching works:

• Host comparison only — scheme, port, and path are ignored
• Case-insensitive ("App.Example.com" matches "app.example.com")
• Exact host match — no wildcards, no subdomain inheritance. If your UI lives at app.example.com and dashboard.example.com, both hosts need to be on the allowlist
• localhost is permitted for local development (the only http:// exception — every other host must be https://)

How to get a domain added:

Allowlist updates are not self-service today. To add or remove a domain, contact your Layers account manager with:

• The API key name or ID (visible on GET /v1/whoami as apiKeyId)
• The domain(s) you want allowed (e.g., app.example.com)
• Your environment context (e.g., "staging" vs "production")

Updates typically take effect within a few minutes of being saved. You don't need to re-mint the API key — the existing key picks up the new allowlist automatically.

Default scopes

If you don't pass scopes in the body, Layers requests the platform-specific default set below. These are the scopes the Layers app has approved with each platform during app review, and they cover everything needed for publishing, metrics, and comment moderation through the Layers API.

TikTok defaults (10 scopes)

Reference: TikTok OAuth scopes catalog (Layers uses the TikTok for Business OAuth flow at the business-api.tiktok.com token endpoint).

Instagram defaults (4 scopes)

Reference: Instagram Login permissions (Layers uses the Instagram Business Login flow at api.instagram.com/oauth/access_token — NOT Facebook Login).

Overriding the defaults

You can pass scopes in the request body to override the default set — but with two caveats:

1. Subset only. The platform's app config maps each redirect URI to an approved scope set. Requesting scopes outside what's approved (e.g. adding TikTok's biz.spark.auth or IG's deprecated instagram_basic) will return Invalid redirect_uri post-authentication, even though the URI is byte-correct in the registered list. If you have a real need for a non-default scope set, contact your Layers account manager before going live.

2. Bounds. Max 32 scopes per call, each ≤ 64 characters. Schema enforced at request time; violations return 422 VALIDATION.

If you only need a narrower flow (e.g. metrics-only, no publishing), passing a smaller scope subset of the defaults is supported — the platform's approval allows any subset of the approved set, just not adding new scopes outside it.

Example request

curl https://api.layers.com/v1/projects/prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39/social/oauth-url \
  -H "Authorization: Bearer lp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "returnUrl": "https://app.gicgrowth.com/connect/tiktok/return",
    "usageNote": "Connecting Acme Coffee"
  }'

const { authorizeUrl, state } = await layers.social.createOAuthUrl({
  projectId: "prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
  platform: "tiktok",
  returnUrl: "https://app.gicgrowth.com/connect/tiktok/return",
  usageNote: "Connecting Acme Coffee",
});

window.location.assign(authorizeUrl);

result = layers.social.create_oauth_url(
    project_id="prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
    platform="tiktok",
    return_url="https://app.gicgrowth.com/connect/tiktok/return",
    usage_note="Connecting Acme Coffee",
)
# send result["authorizeUrl"] to the end-customer's browser

Response

{
  "authorizeUrl": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=st_01HXZ8...",
  "state": "st_01HXZ8K2M4P5QRS6TUV7WXYZ9A",
  "expiresAt": "2026-04-18T19:12:11Z"
}

The returned state is a Layers-created opaque token - do not reuse or modify it. When the end-customer returns to your returnUrl, Layers appends ?layers_oauth_error=<code> only on failure (the success case carries no extra params - Layers has already persisted the social account). Pass the same state to GET /v1/social/oauth-status/:state to learn the resulting socialAccountId.

The authorize URL host depends on platform: TikTok → www.tiktok.com/v2/auth/authorize, Instagram → www.instagram.com/oauth/authorize (Instagram Login flow, not Facebook Login). Both reject framing in iframes — open in a top-level tab.

Authorize URLs and state tokens expire after 10 minutes. After expiry, create a new one — do not cache. On expiry the state moves to failed with error.code = state_expired.

What lands at your returnUrl

After consent (success or failure), Layers redirects the user's browser to the returnUrl you supplied. On success the URL is clean — no query params added — and your job is to call oauth-status with the state you've already stored to learn the resulting socialAccountId. On failure Layers appends ?layers_oauth_error=<code> so your handler can branch on it.

Codes that can appear in ?layers_oauth_error (snake_case, stable contract — additive only):

When the state row can't even be loaded (state token unknown, or the URL has no state param at all), Layers can't redirect — there's no recoverable returnUrl. The user sees a Layers-hosted "Invalid or expired state" page instead. Design your UI to handle the case where the user never comes back to your returnUrl at all.

The same six failure codes (every one above except state_terminal) also surface on oauth-status as error.code on a failed status — so a partner that prefers polling-only doesn't need to parse returnUrl query params. state_terminal is specific to returnUrl (it represents a replay, not a fresh failure).

State token handling

state is the handle you keep between minting the authorize URL and learning the resulting socialAccountId. A few things worth pinning down before you ship:

• Store it server-side, not in a cookie. Keep it in your session store (Redis, your DB, signed JWTs you own) keyed by the user's session. The state itself is the lookup token Layers needs back — losing it means the partner can't poll oauth-status or recover the new socialAccountId. A cookie the user can read or clear is not safe primary storage.
• You don't need your own CSRF token. Layers' state is opaque, scoped by API key, and validated server-side at every callback. Adding a second CSRF layer is harmless but redundant — Layers' state validation is the security property.
• state is sensitive-ish. Treat it like a session ID: don't log it in plaintext where a customer-facing log search can reach, don't expose it cross-tenant. It isn't a credential (it can't sign requests on its own), but it does grant read access to one specific OAuth attempt's result. The expiresAt window (10 min) limits blast radius.
• If your server restarts mid-flow, the handshake is lost. The state row Layers holds is still valid until expiry, but without your stored copy you can't poll oauth-status for the result. Persist state to durable storage before redirecting the user, not just in-process memory.
• One state per attempt. Don't reuse state across retries — if the row is failed or completed, Layers refuses to re-process it (state_terminal). Mint a fresh URL for each retry.

Errors

See Errors for the canonical envelope and full code catalog. Endpoint-specific notes:

See also

• GET /v1/social/oauth-status/:state - poll completion (not project-scoped)
• GET /v1/projects/:projectId/social-accounts - list connected accounts
• POST /v1/projects/:projectId/social/reauth-url - refresh an existing connection
• Social accounts - how Layers stores and refreshes tokens