Getting started

Authentication

Every request carries a developer key as a bearer token. A key acts as the member who created it, inside that member's workspace, with every row-level rule the dashboard applies.

curl

curl https://crm.ashwanth.dev/api/v1/dashboard \
  -H "Authorization: Bearer se_YOUR_KEY"

Creating a key

Settings, Developer API, Create key. Name it after what will use it and tick the scopes it needs. The secret is shown once: only a SHA-256 hash is stored, so neither you nor we can read it back. Lose it, revoke it, create another.

Keep it the way you keep any secret. An environment variable is the usual answer:

Shell

export SALES_ENGINE_API_KEY="se_..."

curl https://crm.ashwanth.dev/api/v1/settings \
  -H "Authorization: Bearer $SALES_ENGINE_API_KEY"

Key format

A key is se_ followed by 40 letters and digits. The prefix makes a leaked key easy to grep for in a repository and easy to recognise in a log. The first eleven characters are what Settings shows as the key's name tag.

Scopes

Scope	Lets a key
`read`	Read anything in the workspace. Every key can read, whatever else it holds.
`write`	Create and edit lists, research, sequences, campaigns, memory, signals and learning; queue jobs.
`send`	Anything that sends email or changes what sends: launch, pause, resume, test sends, replies, draft approval, mailbox pause.
`admin`	Provider keys, developer keys, mailboxes, domains, settings, fixed costs.

Each reference page names the scope it needs. A key without it gets 403 insufficient_scope and details.required_scope says which; the key is fine, make one with the right scope rather than rotating it. For anything that runs unattended, a read key is the right default.

Revocation

Revoking a key in Settings takes effect on its next request. Revoked keys stay listed so the record of what existed, and what it last did, is kept.

The browser session

Signed in to the app, the same endpoints answer to the session cookie with no key at all; that is how the dashboard calls them, and how the Try it panel on each reference page works when you leave the key blank. A session belongs to one user who may hold several workspaces; add x-workspace-id to pick one, otherwise the workspace you last opened is used.

A few calls are browser-only and refuse a key with 403 session_only: your own profile, avatar and Google connection, creating and switching workspaces, and image uploads for email bodies. They are not in this reference.

What every call leaves behind

Each request made with a key, including one that was refused, is logged with its operation, status and duration. Settings, Developer API, Calls shows the last fifty per key, and the same list is an endpoint.