Authentication

Try signed requests in your browser at the API Sandbox — paste your API key and secret, and the playground signs requests automatically.

The SalesOS Integration API uses the P2S-SIGN-V1 signed-request scheme in the Authorization header. API Keys are scoped to a single tenant, hashed with bcrypt, and support rate limiting and IP allowlists.

Scheme	When to use	Format
P2S-SIGN-V1	Server-to-server API calls — signed with the API key secret	`P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`

Environments

Production
Staging

Base URL: https://api.play2sell.comDashboard: https://dashboard.play2sell.comApp: https://app.play2sell.com

Base URL: https://api-staging.play2sell.comDashboard: https://dashboard-staging.play2sell.comApp: https://app-staging.play2sell.com

Quick Start

1. Create an API Key

Go to Integrations > API Keys in the SalesOS Dashboard:

Click Create API Key
Name your key (e.g., “CRM Nightly Sync”, “Website Form Integration”)
Select the scope: default:sync
Click Create
Copy both values immediately — they are only shown once:
- API Key — public identifier, e.g. sk_live_a1b2c3d4...
- API Key Secret — used to sign requests, never sent over the wire

2. Sign and Send a Request

For server-to-server calls, build the Authorization header as P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. The signature is hex HMAC-SHA256 of a 5-step derived-key chain:

k1 = HMAC_SHA256(key=API_KEY_SECRET, msg=API_KEY)
k2 = HMAC_SHA256(key=k1, msg=TIMESTAMP)
k3 = HMAC_SHA256(key=k2, msg=METHOD)
k4 = HMAC_SHA256(key=k3, msg=PATH)
SIG = HMAC_SHA256_HEX(key=k4, msg=PAYLOAD_SHA256_HEX)

TIMESTAMP is Unix epoch seconds, valid for 30 seconds. PAYLOAD_SHA256_HEX is the lowercase hex SHA-256 of the raw request body (use the empty-string digest e3b0c4...b855 if there is no body).

Node.js
Python
Bash

import crypto from 'node:crypto';

const API_KEY = process.env.SALESOS_API_KEY;
const SECRET  = process.env.SALESOS_API_SECRET;

const hmac = (key, msg) =>
  crypto.createHmac('sha256', key).update(msg).digest();

async function signedRequest(method, path, body) {
  const ts          = Math.floor(Date.now() / 1000).toString();
  const bodyStr     = body ? JSON.stringify(body) : '';
  const payloadHash = crypto.createHash('sha256').update(bodyStr).digest('hex');

  const k1  = hmac(SECRET, API_KEY);
  const k2  = hmac(k1, ts);
  const k3  = hmac(k2, method);
  const k4  = hmac(k3, path);
  const sig = hmac(k4, payloadHash).toString('hex');

  const res = await fetch(`https://api.play2sell.com${path}`, {
    method,
    headers: {
      Authorization: `P2S-SIGN-V1 ${API_KEY}:${ts}:${sig}`,
      'Content-Type': 'application/json',
    },
    body: bodyStr || undefined,
  });
  return res.json();
}

import hashlib, hmac, json, os, time, requests

API_KEY = os.environ['SALESOS_API_KEY']
SECRET  = os.environ['SALESOS_API_SECRET']

def hmac_raw(key: bytes, msg: str) -> bytes:
    return hmac.new(key, msg.encode(), hashlib.sha256).digest()

def signed_request(method: str, path: str, body=None):
    ts           = str(int(time.time()))
    body_str     = json.dumps(body) if body else ''
    payload_hash = hashlib.sha256(body_str.encode()).hexdigest()

    k1  = hmac_raw(SECRET.encode(), API_KEY)
    k2  = hmac_raw(k1, ts)
    k3  = hmac_raw(k2, method)
    k4  = hmac_raw(k3, path)
    sig = hmac_raw(k4, payload_hash).hex()

    return requests.request(
        method, f'https://api.play2sell.com{path}',
        headers={
            'Authorization': f'P2S-SIGN-V1 {API_KEY}:{ts}:{sig}',
            'Content-Type': 'application/json',
        },
        data=body_str or None,
    ).json()

API_KEY="sk_live_..."
SECRET="..."
METHOD="POST"
PATH_="/functions/v1/default-integration/sync_collaborators"
BODY='{"action":"sync_collaborators","collaborators":[{"external_id":"emp-101","name":"Maria Santos","email":"maria@yourcompany.com"}]}'
TS=$(date +%s)

PAYLOAD=$(printf '%s' "$BODY"        | openssl dgst -sha256 -hex                                  | awk '{print $2}')
K1=$(printf '%s'      "$API_KEY"     | openssl dgst -sha256 -hmac "$SECRET" -hex                  | awk '{print $2}')
K2=$(printf '%s'      "$TS"          | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K1" -hex   | awk '{print $2}')
K3=$(printf '%s'      "$METHOD"      | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K2" -hex   | awk '{print $2}')
K4=$(printf '%s'      "$PATH_"       | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K3" -hex   | awk '{print $2}')
SIG=$(printf '%s'     "$PAYLOAD"     | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K4" -hex   | awk '{print $2}')

curl -X "$METHOD" "https://api.play2sell.com$PATH_" \
  -H "Authorization: P2S-SIGN-V1 $API_KEY:$TS:$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Don’t want to write the signing code yet? The API Sandbox signs requests for you in the browser — paste your API key and secret, then click Try it out.

3. Check the Response

Success (200):

{
  "data": { "created": 1, "existing": 0, "errors": [], "total": 1 },
  "meta": { "request_id": "f47ac10b-...", "timestamp": "2026-03-17T10:30:00.000Z" }
}

Invalid signature or timestamp outside the window (401):

{ "error": "Signature does not match", "code": "signature_invalid" }

API Key Properties

Property	Details
Prefix	`sk_live_` (production) or `sk_test_` (testing)
Scope	`default:sync` — enables `sync_collaborators` and `sync_activities`
Rate limit	Configurable per key (default: 1000 requests/hour)
Expiration	Optional — set an expiry date or leave as never-expires
IP allowlist	Optional — restrict to specific IP addresses
Storage	Hashed with bcrypt — the plaintext key is never stored

Key Formats

SalesOS uses two key prefixes to distinguish environments:

Prefix	Environment	Use case
`sk_live_`	Production	Real data, real missions, real points
`sk_test_`	Testing	Safe to use during development — no impact on production

Use sk_test_ keys during development and integration testing. Switch to sk_live_ when you go to production.

Authentication Errors

Every rejection from the authentication layer has the same shape: error is a human-readable string and code is stable — branch on code, never on the text.

{ "error": "Signature does not match", "code": "signature_invalid" }

HTTP Status	`code`	Meaning	What to do
401	`header_missing`	No `Authorization` header	Send `Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
401	`header_malformed`	Header not in the `P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE` format	Check the scheme, the colons and that the timestamp is an integer
401	`api_key_not_found`	Unknown or revoked key	Confirm the key in the Dashboard; a revoked key does not come back — request a new one
401	`key_expired`	Key is past its expiration date	Request a new key
401	`signature_invalid`	Signature does not match	Sign the raw body bytes and the exact path, with the right secret
401	`timestamp_too_old`	Timestamp older than 30 seconds	Re-sign every attempt; sync your clock (NTP)
401	`timestamp_in_future`	Timestamp ahead of the server clock	Sync your clock (NTP) — any second in the future is rejected
403	`scope_insufficient`	Valid key without the required scope	Read `missing_scopes` and request the scope on the key

Example: Key without required scope

{
  "error": "API key missing required scopes: checkin:write",
  "code": "scope_insufficient",
  "missing_scopes": ["checkin:write"]
}

missing_scopes only appears in this case.

Rate Limits

Each API key has an independent rate limit counter that resets hourly:

Setting	Default	Range
Requests per hour	1000	10 — 100,000

How it works:

Every authenticated and authorized request counts in the key’s window (authentication rejections do not count)
The window is one hour from the first request
Today the limit is measured but not enforced. Once enforcement is on, excess requests will get 429 with code: "rate_limited" and a Retry-After header in seconds — handle it now

Handling rate limits in code:

// signedRequest() is the helper from the Quick Start above.
async function callWithRetry(method, path, body) {
  const response = await signedRequest(method, path, body);

  if (response.status === 429) {
    const waitSeconds = Number(response.headers.get("Retry-After")) || 60;
    console.log(`Rate limited. Retrying in ${waitSeconds}s...`);
    await new Promise(r => setTimeout(r, waitSeconds * 1000));
    return callWithRetry(method, path, body); // re-signs: the timestamp is valid for 30 s
  }

  return response.json();
}

Security Best Practices

Never expose API keys in client-side code. Browser JavaScript, mobile apps, and public repositories can all leak your key. Always call the SalesOS API from your backend server.

Use environment variables — Store SALESOS_API_KEY in env vars or a secrets manager, never in source code
Rotate keys periodically — Create a new key, update your integration, then revoke the old one
Use IP allowlists — If your integration runs from fixed IPs, restrict the key to those IPs only
Monitor usage — Check the API usage logs in the Dashboard for unexpected patterns
Use sk_test_ for development — Test keys isolate your dev environment from production
Revoke compromised keys immediately — Go to Dashboard > Admin > API Keys > Revoke

Key rotation example

# 1. Create new key in Dashboard → copy both values:
#    - SALESOS_API_KEY=sk_live_NEW_KEY
#    - SALESOS_API_SECRET=NEW_SECRET
# 2. Update both env vars in your deployment.
# 3. Verify it works using the signed request helper from the Quick Start
#    (Node, Python, or Bash). Example payload:
#    { "action": "sync_collaborators",
#      "collaborators": [{"external_id":"test","name":"Test","email":"test@co.com"}] }
# 4. Revoke the old key in Dashboard.

Overview

Integrations

Authentication

Authentication

Environments

Quick Start

1. Create an API Key

2. Sign and Send a Request

3. Check the Response

API Key Properties

Key Formats

Authentication Errors

Example: Key without required scope

Rate Limits

Security Best Practices

Key rotation example

Next Steps

Default Integration

API Keys

​Authentication

​Environments

​Quick Start

​1. Create an API Key

​2. Sign and Send a Request

​3. Check the Response

​API Key Properties

​Key Formats

​Authentication Errors

​Example: Key without required scope

​Rate Limits

​Security Best Practices

​Key rotation example

​Next Steps

Default Integration

API Keys

Authentication

Environments

Quick Start

1. Create an API Key

2. Sign and Send a Request

3. Check the Response

API Key Properties

Key Formats

Authentication Errors

Example: Key without required scope

Rate Limits

Security Best Practices

Key rotation example

Next Steps