Authentication

The API authenticates requests with a bearer token in the Authorization header:

Authorization: Bearer srk_live_5f3a1c...

There is no OAuth flow today — a token is a long-lived credential you generate directly in the app and pass with every request. OAuth 2.1 (for third-party and agent integrations that shouldn’t share a static token) is designed and roadmapped, not yet built — this page will be updated when that ships.

Live vs. test tokens

Every token is prefixed by its environment:

• srk_live_... — acts on real data in your workspace.
• srk_test_... — intended for testing. At present this is a naming convention only; test tokens run against the same database as live tokens, so treat test-prefixed credentials with the same care as live ones until sandboxed test environments ship.

Scopes

Tokens are created with a specific set of scopes — string permissions like surveys:read, surveys:write, distribution:write, or contacts:suppress — rather than blanket account access. A request fails with insufficient_scope (see Errors) if the token’s scopes don’t cover the action being called.

Some representative scopes:

Scope	Grants
surveys:read / surveys:write	Survey CRUD, settings, elements
responses:read / responses:write	Read responses/aggregates; submit responses
distribution:read / distribution:write	Distributors — web links, QR codes, embeds
contacts:read / contacts:write	Contact CRUD, import
contacts:suppress	Unsubscribe/suppression — kept separate from contacts:write since it’s consent-sensitive
reports:export	Generate and download response exports
events:read	Read webhook subscriptions, their delivery logs and the event feed
events:write	Create, change, test and delete webhooks and event feeds (includes events:read)

For reports:export, CSV and Excel exports work on every plan that has API access, and SPSS export needs Growth and above.

events:write has to be chosen by name. A token created with every scope doesn’t include it, because a token that can add a webhook can send a workspace’s events to any address. See Webhooks and Events.

Grant only the scopes an integration actually needs. The full, current scope list is visible when creating a token in the app. Token management itself (creating, rotating, revoking) isn’t part of the API — it’s app-only, from Settings → API Tokens; see Rotating and revoking tokens below.

Tenancy

A token acts as the person who created it. It can reach the workspaces that person belongs to, with the role they hold in each, narrowed to the token’s scopes, and it can never reach a workspace they aren’t a member of. Access is checked on every request, so removing someone from a workspace cuts off their tokens there at once.

A request about a specific resource, such as a survey or a contact, applies to the workspace that owns it. A request that lists or creates applies to the token owner’s workspace when they belong to only one. If they belong to more than one, name the workspace with the X-Workspace-ID header: a request that could mean more than one workspace is refused with workspace_required rather than guessed. To limit an integration to a single workspace, create its token as a user who belongs only to that workspace.

Rotating and revoking tokens

Tokens can be rotated or revoked from Settings → API Tokens in the app at any time, with immediate effect. There’s no grace period on revocation — a revoked token starts failing authentication on its very next request.