API Keys

How do I create an API key?

Go to Settings, then API Keys, and click Create API Key. Name it, tick any scopes an AI assistant should have, optionally set an expiry, and copy the key — that is the only time it is shown. You need the Business or Business Plus plan, and only the account owner can open the page. Scopes limit an AI assistant only: over the REST API every key still acts with full account authority. Delete a key to revoke it immediately.

An API key lets software reach your Survtapp account without signing in as a person. One key can drive your own scripts over the REST API, or connect an AI assistant.

API keys need the Business or Business Plus plan, and only the account owner can open Settings → API Keys. Admins, managers, agents and read-only users do not see the page.

Creating a key

1. Go to Settings → API Keys and click Create API Key.
2. Give it a name you will recognise later — the field suggests something like "Production API Key". Name it after the thing that will use it.
3. Under Scopes, tick what an AI assistant connected with this key may do. Nothing is ticked by default. Leave them all unticked for a key that only drives your own software over the REST API.
4. Optionally set Expiration (Optional). Leave it empty and the key never expires.
5. Click Create API Key, then copy the key. This is the only time you will see it — Survtapp stores a hash, not the key, and cannot show it again.

What the scopes do — and what they do not

Read this part carefully, because the checkboxes are narrower than they look. Scopes apply to the MCP connector only; the REST API is unaffected by them, exactly as the page itself says. Over the REST API every key acts with your account owner’s authority whatever you ticked — so a key you scoped to Read forms can still change and delete data through the REST API. A scope limits what an AI assistant may do with the key. It is not a read-only key.

• Read forms (forms:read) — list your surveys, checklists and waivers and read their questions and settings.
• Create and edit forms (forms:write) — create a form as a draft and change an existing form’s title, description or status. It cannot publish a form.
• Read responses (responses:read) — list and read submitted responses, and read per-question result summaries.
• Read contacts (contacts:read) — list your contacts and read one contact with their response history.

There is no scope for submitting responses, and no assistant tool does it. Responses are collected in the web and mobile apps only.

A scope also does not narrow which records a key can reach. Within your account, Read forms means every form and Read contacts means every contact; there is no way to limit a key to one form, one project or one team. Scopes are fixed when the key is created — to change them, create a new key and delete the old one.

Keys you already have

A key created before scopes existed shows Full access (legacy). That label means what it says: over the REST API such a key can read and change everything in your account. It is not a key with no access. An AI assistant cannot use it — connecting with one is refused — so your existing scripts keep working exactly as before while assistants get only what you deliberately tick.

Living with your keys

The list shows each key by its first few characters only, with its scope badges, when it was last used or Never used, and an Expired badge once its date has passed. Delete a key to revoke it; it stops working immediately. Create one key per thing that uses it, so you can switch one off without disturbing the others, and treat a key like a password — never paste one into a chat, a ticket or a shared document.

Why a key stopped working

• "API access is not part of your current plan. Upgrade to Business or Business Plus to use the API." — the plan is re-checked on every single request, so a downgrade stops every existing key at once rather than at renewal.
• "This API key has been revoked" — it was deleted. Create a new one.
• "This API key has expired" — its expiry date has passed. Create a new one.
• "Invalid API key" — the key is wrong, or the account is suspended or closed.

For connecting an AI assistant — the address, the header and a worked example — see the MCP connector documentation at /docs/mcp.