Authentication and access tokens

API plan access: External personal/service tokens require the workspace’s configured api capability (Pro by default). New issuance and bearer requests return pro_required when it is unavailable. Roles, scopes and project restrictions still apply. Free browser authoring, public collection, documentation, token inventory and revocation remain available. Downgrade retains credentials; eligible recovery restores unexpired, unrevoked tokens without resetting usage.

Report creation and queued writes recheck access before saving. Long result reads recheck before returning data. Response CSV downloads recheck between batches; if access expires after headers were sent, the download fails rather than returning a JSON error. Treat an interrupted download as incomplete, discard it, and retry after access is restored. Previously delivered bytes cannot be recalled.

The console signs researchers in with Google. Server-side integrations use scoped bearer tokens created under Workspace settings → API tokens. Keep token secrets out of URLs, source control, and browser storage. The secret appears only when issued.

Browser sessions

Sign in through the console.
Call GET /api/v1/me to read the CSRF token and available workspaces.
For every browser write, send the session cookie, x-csrf-token, and a same-origin Origin header.

The server checks workspace membership and role for each resource.

Bearer tokens

Send Authorization: Bearer ACCESS_TOKEN. Each token belongs to one workspace and may optionally be restricted to one project. A personal token belongs to its creator; only that user can list or revoke it, and it stops working when their workspace membership ends. A service token belongs to the workspace; owners and admins can list or revoke it and it keeps working when its creator leaves. Explicit scopes are independent; wildcards are presets:

Scope	Allows
`*`	Every permission in this table, including response results.
`projects:read`	List and read projects.
`reports:write`	Save private reports and project research briefs; also requires `responses:read` and an editor role.
`responses:read`	Read survey results, saved private reports and full CSV exports.
`surveys:*`	Read, create, validate, edit, and publish surveys. Does not read projects or responses.
`surveys:create`	Create surveys in existing projects.
`surveys:publish`	Publish a valid draft.
`surveys:read`	List surveys and read drafts.
`surveys:write`	Save and validate drafts.

Use either wildcard scope by itself; it cannot be combined with other scopes. A viewer cannot issue a wildcard authoring scope. Wildcards cover the listed token actions, not workspace administration or platform staff access. Personal tokens retain the issuer's workspace role limits. Owners and admins can issue service tokens. Tokens cannot create projects, manage membership, submit respondent answers, or request/resume research deletion. Deletion requires the workspace owner’s signed-in session and CSRF protection. Revocation takes effect immediately.

Identity collisions

A new Google identity cannot automatically attach to an account that already owns its verified email address. The callback returns 409 with guidance to use the existing sign-in method. Explicit linking of a new Google identity is not available yet. Existing Google identities continue using their existing account. Conflicting duplicate email owners fail safely instead of choosing or merging accounts.

Errors

API failures return a JSON error object with code and message. 401 means missing or invalid credentials, 403 means insufficient access, 404 hides inaccessible resources, 409 covers conflicting slugs or revisions, 422 means invalid input or an unpublishable draft, and 423 means the workspace is suspended.