Skip to main content
Talk to salesStart

Authentication and scopes

How to bootstrap agent access, authenticate with developer API keys, and apply scopes for tables, sequences, and task workflows.

Updated March 3, 2026

This page recommends the Autotouch CLI for the fastest execution path. Use the API reference when you need the raw HTTP contract.

Base URL

Use your API host with the /api prefix. Example: https://app.autotouch.ai/api.

Agent bootstrap (register + key in one call)

Use POST /api/auth/agent-bootstrap when an agent needs to create an account/org and start API usage immediately.

curl -X POST "https://app.autotouch.ai/api/auth/agent-bootstrap" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@yourcompany.com",
    "password": "use-a-strong-random-password",
    "organization_name": "Your Company",
    "key_name": "Agent bootstrap key"
  }'

The response returns apiKey once, plus userData, key metadata, and org/user credit snapshot.

New organizations start with a configurable starter-credit pool that defaults to 50; the returned credits object is authoritative for the account created.

Developer API key format

Developer keys are issued in this format:

stk_{key_id}.{secret}

Passing the key

Use either header format below:

Authorization: Bearer stk_...

X-API-Key: stk_...

Identity headers such as X-User-Email and X-User-Id are not credentials. Send a valid developer key on every API request; use the endpoint's stated user-session requirements where developer keys are blocked.

CLI uses the same key and scopes

The CLI supports developer API keys and signed-in user session tokens. Developer-key calls follow the same scope checks as raw HTTP requests. Session-only endpoints such as Scheduled Chat require session authentication in the CLI; adding scopes to a developer key does not enable them.

autotouch auth set-key --api-key stk_... --base-url https://app.autotouch.ai
autotouch auth check

Coverage note: the CLI covers the main public research-table, lead, sequence, task, and workflow helper surfaces. Raw HTTP remains the canonical contract and is what the API Reference documents.

Developer API key scopes

These scopes cover the current supported developer-key API families. Compatibility scope names retained by the key system do not restore retired endpoints. Route access still depends on the endpoint mapping: some routes require several scopes together, and some session-only routes remain blocked even when a related scope exists. Check each endpoint reference for its exact access rule.

Scope Description
notes:read Read notes, revisions, and journals.
notes:write Create or update notes and create journals; this does not grant notes:read.
calendar:read Read connected personal Calendar accounts and events when Calendar is enabled.
calendar:write Send, edit, or cancel supported Lead meetings when Calendar is enabled.
tables:read Read tables, columns, and rows.
tables:write Create/update tables, rows, and cells.
columns:write Create/update/reorder/delete columns.
columns:run Estimate, run, or stop column operation runs.
leads:read Read/query leads and selected lead research routes.
leads:write Create, update, import, or delete leads and selected lead operations.
companies:read Read/search companies and company data.
companies:write Create, update, import, or delete companies.
signals:read Read saved Signals, source catalog, monitor/subscription state and supported capability discovery. This does not grant general CRM reads.
signals:write With Signals Read, manage company monitoring/enrollment. Discovery monitor create/update also needs Signals Run.
signals:run With Signals Read, preview discovery source searches; discovery monitor create/update/run needs all three Signals scopes and can schedule paid collection.
workspace_views:read Read saved workspace views.
workspace_views:write Create, update, or delete saved workspace views.
integrations:read Read supported integration and connected-account metadata.
integrations:write Manage the supported API-key integration operations.
jobs:read Read canonical operation-run progress and native executor status metadata.
sequences:read Read sequences and sequence stats/status.
sequences:write Create/update/delete/clone sequence definitions.
sequences:run Activate/pause/archive and enroll/pause sequence enrollments.
users:read Read organization users on the supported user-list route.
tasks:read Query and read workflow tasks.
tasks:write Create/update/delete tasks, bulk mutate, and draft/schedule task emails.
webhooks:read List webhook subscriptions and delivery history.
webhooks:write Create/update/delete webhook subscriptions and test-fire events.
linkedin:read Read LinkedIn integration status, limits, search, and post data.
search:run Run company, people, news, and other public-web searches, plus authenticated list-build job operations and input searches. Table sync uses table scopes.
secrets:read List workspace secrets (values are masked).
secrets:write Create/update/delete workspace secrets.
prompts:read List prompt templates.
prompts:write Create/update/delete prompt templates.
* Wildcard scope accepted by the key system; endpoint-specific session-only blocks still apply.

When no explicit scopes are supplied during key creation, the backend grants the default set: tables:read, tables:write, columns:write, columns:run, and jobs:read. Scope combinations are route-specific; for example, some compound operations require every listed scope, while an | mapping accepts either alternative.

Create a key for Signals

In Settings → Developer API, select the Signals Read, Write and Run permissions needed by your integration and deselect unrelated permissions for a Signals-only key. Read alone supports saved evidence, catalogs and monitor state. Company monitoring/enrollment needs Read and Write. Discovery preview needs Read and Run; discovery monitor create, update, pause/resume and explicit run need all three because updates can schedule paid collection. Existing keys keep their scopes; the complete legacy Company/Lead/Search combinations remain supported on the corresponding Signals routes.

Signals permissions do not grant access to general Companies, Leads or Search endpoints. Saving a person to Leads additionally requires leads:write; supported Research Table destination/creation actions retain their table scopes. Developer keys still cannot access session-only helpers. The CLI uses these same API permissions.

Related pages

Docs