Authentication & workspace scoping

How to authenticate against the Well API and how every request is scoped to a workspace.

Every /v1 request is authenticated and workspace-scoped. Authentication proves who you are; workspace scoping decides which tenant's data you can see. Both are required on every call.

Base URL

https://api.wellapp.ai/v1

Authentication methods

The public API accepts two credential types. Send exactly one as a bearer token.

MethodHeaderUse it for
API key (recommended for server-to-server)Authorization: Bearer <api_key>Backend integrations, scripts, SDKs
OAuth2 JWTAuthorization: Bearer <jwt>OAuth/DCR-issued access tokens (e.g. MCP clients)
First-party Well web and mobile clients authenticate with an internal session token. That mechanism is not part of the public API contract — integrations use an API key or an OAuth2 JWT.
curl https://api.wellapp.ai/v1/companies \
  -H "Authorization: Bearer YOUR_API_KEY"

A missing or invalid credential returns 401 UNAUTHORIZED (see Errors).

Getting an API key

Create and manage API keys via the API Keys endpoints (POST /v1/api-key, GET /v1/api-key, DELETE /v1/api-key/{id}). Store the key secret at creation time; it is not retrievable afterwards.

Workspace scoping

Well is multi-tenant. Every data row belongs to a workspace, and the API enforces this at two layers:

  1. Resolution — the request resolves an effective workspace. Pass ?workspaceId=<uuid> to target a specific workspace; the server validates you have an active membership on it (or group access to it). Omit it to use your default workspace. An unpermitted workspaceId returns 403 FORBIDDEN.
  2. Row-level security — the resolved workspace is enforced by Postgres/Hasura RLS on every query. You can never read or write rows outside your resolved scope, regardless of the filter you send.
# target a specific workspace you belong to
curl "https://api.wellapp.ai/v1/companies?workspaceId=9f3e…e2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Workspace groups

A parent workspace in a workspace group can read its descendant workspaces' rows. Scoping to a parent therefore returns the group's combined records; scoping to a child returns only that child's. Group membership is what authorizes the cross-workspace read — not a wildcard.

Rate limits

Public endpoints are rate-limited per IP (auth endpoints more strictly). AI-backed endpoints (e.g. POST /v1/custom-columns/infer) are additionally limited to 20 requests/minute per workspace and return 429 when exceeded.

Authentication and workspace scoping are documented once here and apply to every operation — they are not repeated on each endpoint page.