Authentication

Overview

Every Connect API request must include a valid credential. Scoperly supports two authentication methods:

1. API Key (Direct) — pass your secret key as a Bearer token. Simple, no token exchange needed.
2. JWT Exchange — exchange your API key for a short-lived JWT. Use when you need expiry control or want to avoid sending the key with every request.

API Key Format

All Scoperly Connect keys use the sck_live_ prefix and operate on live data — there is no sandbox environment. Test carefully against a non-production tenant of your own if you need a safe playground.

Authorization: Bearer sck_live_a1b2c3d4e5f6...

Token Exchange

curl -X POST https://api.scoperly.com/connect/v1/auth/token \
  -H "Authorization: Bearer sck_live_abc123def456..." \
  -H "Content-Type: application/json"

# Response:
# {
#   "access_token": "eyJ...xxxxx",
#   "token_type": "Bearer",
#   "expires_in": 1800,
#   "refresh_token": "crt_..."
# }

Refresh Flow

The response has the same shape as /auth/token (access_token, token_type, expires_in, refresh_token). The refresh token rotates on every use — always store the newly returned refresh_token; the one you just sent is invalidated. Each refresh token nominally lives 30 days, but the whole session is hard-capped at 7 days from the original /auth/token exchange (see below) — after that, refresh returns 401 and you must re-exchange the API key.

curl -X POST https://api.scoperly.com/connect/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "crt_..." }'

# Response:
# {
#   "access_token": "eyJ...xxxxx",
#   "token_type": "Bearer",
#   "expires_in": 1800,
#   "refresh_token": "crt_...(NEW — replaces the one you sent)"
# }

Scopes

API keys can be scoped to limit their access. When creating a key, select only the scopes your integration needs.

Verifying which account a key belongs to

Call this once during setup, before you push any catalog data or consume any orders, and check that side is SUPPLIER and that tenantSlug is the account the operator expected. An integration configured with the wrong key otherwise discovers the mistake only by observing the damage afterwards.

curl https://api.scoperly.com/connect/v1/me \
  -H "Authorization: Bearer $TOKEN"

# Response:
# {
#   "tenantId": 118,
#   "tenantUuid": "9c1b1f2e-...-...-...-...",
#   "tenantSlug": "avan-dairy",
#   "tenantName": "Avan Dairy",
#   "legalName": "Avan Dairy LLC",
#   "countryCode": "AM",
#   "side": "SUPPLIER",
#   "scopes": ["catalog:read", "catalog:write", "orders:read", "orders:write"],
#   "keyName": "Studio production",
#   "keyPrefix": "sck_live_a1b2",
#   "planTier": "PROFESSIONAL",
#   "keyExpiresAt": null
# }

Session-age cap (7 days)

The refresh-token flow keeps a session alive across many access-token rotations, but there is a hard 7-day upper bound measured from the original POST /auth/token call. After that window, even a valid refresh_token returns 401 — your integration must re-exchange its API key (sck_live_*) for a fresh session.

This cap is server-enforced and not client-configurable. It limits the blast radius of a stolen refresh token: even with the token in hand, an attacker cannot pivot a session beyond 7 days without also compromising the API key.

Key Rotation

We recommend rotating keys periodically. Scoperly supports zero-downtime rotation:

1. Create a new key using the API key management endpoints.
2. Update your integration to use the new key.
3. Verify traffic is flowing on the new key (check the “Last used” timestamp).
4. Revoke the old key once no traffic remains.