Authentication

The SuprSync External API uses API key pairs for authentication. Every request must include both your client ID and client secret in the request headers.

Headers

Example

curl -X GET "${SUPRSYNC_API_BASE}/external/v1/locations" \
  -H "x-api-key: api_a1b2c3d4e5f6a1b2c3d4e5f6" \
  -H "x-api-secret: sec_abcdef1234567890abcdef1234567890abcdef1234567890"

Obtaining Credentials

API credentials are generated by a company super admin from this developer portal:

1. Sign in to the developer portal and open Dashboard.
2. Click Create API Key and provide a name for the integration.
3. Copy both the Client ID and Client Secret immediately.

⚠️ Caution: The client secret is shown only once at creation time. Store it securely. If lost, you must rotate the key to receive a new secret.

Idempotency for write requests

Every POST, PATCH, and DELETE resource request must include an Idempotency-Key header containing 8–128 URL-safe characters. Generate a new value for each logical operation and reuse that same value only when retrying the identical method, path, and body. Completed retries return the original response with Idempotent-Replayed: true; reusing a key for a different request returns 409 Conflict.

-H "Idempotency-Key: booking-sync-01J9JH8T3P6AM7QK4D6F2C8B9N"

Key Management

Rotating Keys

If a secret is compromised or you need to refresh credentials, an admin can rotate the key from the dashboard. This generates a new secret while keeping the same client ID.

Revoking Keys

Admins can revoke an API key at any time. Once revoked, all requests using that key will receive a 401 Unauthorized response.

Security Best Practices

• Store credentials in environment variables or a secrets manager. Never hard-code them.
• Use server-to-server calls. Do not expose credentials in client-side code.
• Rotate keys periodically and immediately if a compromise is suspected.
• Each integration should use its own API key for auditability.
• Grant only the scopes it needs: workforce:read, availability:read, workforce:write, and/or webhooks:manage.
• Legacy credentials without stored scopes are limited to workforce read/write compatibility and do not grant availability:read or webhooks:manage.
• Use expiry and literal IPv4/IPv6 allowlists where appropriate. CIDR ranges are not accepted.

Error Responses

{
  "error": {
    "code": 401,
    "message": "Missing API credentials"
  }
}

{
  "error": {
    "code": 401,
    "message": "Invalid API credentials"
  }
}