Authentication

Personal API key

Create a key under Settings → Access. Default scope is full_access. Send it as a Bearer token:

curl -X POST "https://<gateway>/api/v1/tickets/list" \
  -H "Authorization: Bearer sl_api_..." \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"<workspace-id>"}'

Keys act as the workspace profile that owns them. Treat them like passwords; revoke compromised keys from Settings. Workspace / metric ingest API keys (metric_data_only) are removed — use a personal key instead.

OAuth user token

Third-party OAuth apps receive sl_oat_... access tokens after the authorization-code flow (user actor). Send them the same way:

curl -X POST "https://<gateway>/api/v1/tickets/list" \
  -H "Authorization: Bearer sl_oat_..." \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"<workspace-id>"}'

OAuth app actor

Install an app as a machine identity (Linear-style) with actor=app on authorize, or mint a token with grant_type=client_credentials when the app has client credentials enabled.

Authorize: workspace admin only; POST /api/v1/auth/oauth/authorize with actor=app. Creates an app-scoped token with profileId: null.
Client credentials: POST /api/v1/auth/oauth/token with grant_type=client_credentials, client_id, and client_secret. TTL ≈ 30 days. Changing scopes or rotating the secret revokes outstanding machine tokens.
App actors run as a synthetic member (writer) profile oauth-app:{appId} — enough for work-graph reads/writes, not Settings/admin powers.
An admin OAuth scope is not grantable to app actors.

curl -X POST "https://<gateway>/api/v1/auth/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=sl_app_...&client_secret=sl_secret_..."

Use the returned access_token (sl_oat_...) like any other Bearer credential. The TypeScript SDK accepts it via accessToken.

Resource scopes

Coarse scopes remain for back-compat. Resource scopes narrow access per domain.

Domain	Read	Write
tickets	`tickets:read`	`tickets:write`
conversations	`conversations:read`	`conversations:write`
messages	`messages:read`	`messages:write`
companies (contacts/notes/docs)	`companies:read`	`companies:write`
teams	`teams:read`	`teams:write`
attachments	`attachments:read`	`attachments:write`
webhooks	`webhooks:read`	`webhooks:write`
workspace (profiles / info)	`workspace:read`	—

Supersets

Credential	Scope	Effective access
Personal API key	`full_access` (default)	All resource read + write
Personal API key	`read`	All `*:read`
OAuth	`write`	All resource read + write
OAuth	`read`	All `*:read`

Missing a required resource scope returns 401 with error.type: INSUFFICIENT_SCOPE.

App session (not for integrations)

The Sayless web app uses cookie session JWTs. That path is for the official client only (including sync). Integrations should use API keys or OAuth — not scraped cookies.

Errors

API key and OAuth failures return a nested envelope:

{
  "error": {
    "type": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "statusCode": 401,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "path": "/api/v1/tickets/list"
}

Branch on error.type (including INSUFFICIENT_SCOPE). See Errors and Rate limits.

Get started

API

Webhooks & platform

SDK

Personal API key

OAuth user token

OAuth app actor

Resource scopes

App session (not for integrations)

Errors

​Personal API key

​OAuth user token

​OAuth app actor

​Resource scopes

​App session (not for integrations)

​Errors

​Related

Personal API key

OAuth user token

OAuth app actor

Resource scopes

App session (not for integrations)

Errors

Related