Authentication

Authenticate to the Asks API with a workspace API key, and limit what each key can do with scopes.

The API authenticates with a workspace API key, passed as a Bearer token. Every request is scoped to the key's workspace — a key can never read or write another workspace's data.

Plan requirement — API keys and the REST API are available on the Business plan and above. If a workspace downgrades, its keys are kept but every request returns 403 until the plan is upgraded again. See plans and limits.

Create a key

Go to app.asks.app/integrations/api-keys and select Create API Key. A key has:

Key name — a label for your own reference ("Production backend", "Zapier").
Environment — Live or Test. Live keys start with ask_live_, test keys with ask_test_.
Access — Read & write (the read + write scopes) or Read only (the read scope).

The full key is shown once, at creation. Copy it immediately — Asks stores only a SHA-256 hash, so it can never be shown again.

/integrations/api-keys page with the Create API Key dialog open, showing the Key Name field, Environment set to Live, and Access set to Read & write — Keys are created from the API Keys page and shown once.

Test keys are not a sandbox. The environment is a label for organizing your keys — a ask_test_ key authenticates against the same workspace and the same production data as a ask_live_ key. There is no isolated test dataset. Use test keys to separate integrations, not to experiment on throwaway data.

Authorize a request

Send the key in the Authorization header:

Terminal

curl https://api.asks.app/v1/me \
  -H "Authorization: Bearer ask_live_YOUR_KEY"

GET /v1/me returns the workspace, environment, and scopes the key resolves to — useful as a connectivity check.

Scopes

Scopes limit what a key can do. The dashboard's access presets map to the coarse read and write grants; finer per-resource scopes exist for keys minted for a single purpose (the MCP server page, for example, mints keys with agent:chat + agent:read).

Scope	Grants
`*`	Everything.
`read`	Every read action (any `…:read`).
`write`	Every write action — and reads.
`conversations:read` / `conversations:write`	Read vs. create and update conversations (also covers tags and canned responses).
`messages:write`	Send messages into a conversation.
`customers:read` / `customers:write`	Read vs. create and update customers.
`channels:read`	List connected channels.
`tickets:read` / `tickets:write`	Read tickets. The `tickets:write` scope is accepted on keys, but the ticket endpoints are read-only today.
`knowledge_base:read` / `knowledge_base:write`	Read knowledge base articles. The `knowledge_base:write` scope is accepted on keys, but the knowledge base endpoints are read-only today.
`agent:read` / `agent:write`	Read vs. update the agent configuration; `agent:read` also allows knowledge search.
`agent:chat`	Send messages to the AI agent (`POST /agent/messages` and MCP tool calls).
`webhooks:manage`	Manage webhook endpoints and read the event log.

How checks work:

* satisfies everything.
read satisfies any …:read; write satisfies any write-type action (write, chat, manage) and any read.
A resource wildcard such as conversations:* satisfies any action on that resource.

A request missing the required scope returns 403 with code insufficient_scope; the missing scope is listed in error.details.required.

Key lifecycle

Revoke a key at any time from the API Keys page. Revoked keys fail immediately.
Keys can carry an optional expiry; an expired key behaves like a revoked one.
A missing, malformed, expired, or revoked key returns 401 with code unauthorized.

Treat API keys like passwords. Never ship them in client-side code or commit them to source control. If a key leaks, revoke it and create a new one — the old key stops working the moment it is revoked.

← Previous

Overview

Agent chat API