Security

API Key Scopes

Restrict API keys to specific permissions using scopes. Fine-grained access control ensures each integration only has the permissions it needs.

How Scopes Work

Keys can optionally be restricted to a set of scopes. When creating or editing an API key in the dashboard, select only the scopes your integration requires.

A key with no scopes assigned has full account access — this is backward-compatible with existing integrations.

Available Scopes

Scope	Grants
`leads:read`	View leads
`leads:write`	View, update, assign, create, delete leads
`conversations:read`	View conversations and messages
`messages:send`	View conversations + send messages
`campaigns:read`	View campaigns
`campaigns:write`	View + create campaigns
`campaigns:send`	View + send/queue campaigns
`orders:read`	View orders
`orders:write`	View + create/update orders
`catalogue:read`	View product catalogue
`knowledge:read`	View knowledge base sources
`knowledge:write`	View + upload to knowledge base
`agents:read`	View AI agents
`agents:write`	View + create/update agents
`analytics:read`	View analytics and usage
`ai:use`	Use AI simulation endpoint

Scoped Request Example

API Request with Scoped Key

curl -X GET https://dashboard.syncflo.xyz/api/v1/leads \
  -H "Authorization: Bearer sfk_scoped_key_here"

# This key only has leads:read scope
# ✓ GET /api/v1/leads       → 200 OK
# ✗ DELETE /api/v1/leads/123 → 403 Forbidden

Exceeding Key Scope

A request that requires a permission not included in the key's scopes will return a 403 Forbidden response with a clear error message indicating the missing scope.

{
  "error": "Insufficient scope: requires leads:write",
  "code": "forbidden"
}

Scope Best Practices

Follow the principle of least privilege — only grant scopes each integration actually needs.

Use separate API keys for different services (e.g., one for analytics, another for messaging).

Audit key scopes periodically in the dashboard to remove unnecessary permissions.

Combine read and write scopes intentionally — write scopes always include read access for the same resource.

Essentials