Skip to main content

API keys

Connect Zapier, Power BI, AI assistants or your own code to Simplesat with API keys that only read and write what you choose.

API keys let tools and your own code reach your workspace's data through Simplesat's API. Give each tool its own key, decide what that key can read and write, and delete it when the tool no longer needs access.

Owners and Admins can manage API keys, and so can anyone whose custom role includes Access API key. Custom roles come with Premium and above.

How it works

The API keys page is under Admin: click the gear icon at the bottom of the left sidebar, then API keys.

Create as many API keys as you need. Each starts with ssat_ and has Full access or Custom access. Every workspace also has one legacy account key, new workspaces included.

To call the API, send the key in the X-Simplesat-Token header. Both kinds of key work on every REST path: the v1 API (/api/v1/) and the older /api/answers/ and /api/customers/create-or-update/ paths. An API key still needs the scope for whatever it calls. The API itself is covered in API & webhooks.

Keys belong to the workspace, not to the person who created them, and they don't expire.

Create an API key

  1. Go to Admin → API keys and click New API key.

  2. Enter a Key name, such as the tool it's for.

  3. Under Permissions, keep Custom and select the scopes the tool needs, or switch to Full access. A Custom key needs at least one scope.

  4. Click Create API key.

  5. Copy the key from Save your API key and store it somewhere safe, then click Close. This is the only time you'll see the full key.

the Create API key window with Custom selected and the scope table showing Read and Write boxes

From then on, the API keys page shows just the start of the key. Because Simplesat stores only a scrambled copy of it (a hash), no one can show you the full key again, not even our support team. If you lose a key, create a new one.

Scopes

A scope lets a key read or write one kind of data across your whole workspace.

Scope

Read

Write

Answers

✅

✅

Customers

✅

✅

Team members

✅

✅

Responses

✅

✅

Surveys

✅

❌

Questions

✅

❌

Full access covers every scope, including any added later. Custom covers only the scopes you select, and none added later.

Give a reporting tool like Data Studio or Power BI only Read scopes, and its key can't change any of your data.

A Custom key that calls something outside its scopes gets HTTP 403 "You do not have permission to perform this action."

Edit an API key

To see a key's scopes, hover over Custom in the Permissions column. To change its name or access:

  1. Click the ⋮ menu on the key's row, then Edit.

  2. Change the name, select or clear scopes, or switch between Full access and Custom.

  3. Click Save changes.

Changes apply to the key's next call, whether you add a scope or take one away. The key itself stays the same: there's nothing to update in the tool.

Delete an API key

  1. Click the ⋮ menu on the key's row, then Delete.

  2. Click Delete API key.

Warning: Deleting a key can't be undone. Any tool still using it loses access on its next call.

Your other API keys keep working.

The legacy account key

The legacy account key comes from Simplesat's older key system and has full access. Unlike an API key, it doesn't start with ssat_. The API keys page shows its first 20 characters under Legacy account key, but the full value isn't shown anywhere in Simplesat.

An API key does everything the legacy account key does, with scopes you choose. Use an API key for every new connection.

You can't scope, edit or delete the legacy account key in Simplesat. Creating API keys doesn't retire it, and editing or deleting them never changes it. To cut off its full access, contact us to reset it.

Heads up: The old value stops working the moment it's reset. Move anything that still uses it to an API key before you ask.

Which key each tool needs

Here's what each tool asks for when you connect it, and the scopes to select if you give it a Custom key.

Tool

What its setup asks for

Custom scopes it needs

Zapier

An API key

Each action needs the scope for its data. Connecting and the New Feedback trigger need no particular scope.

Make

An API key

Answers Read to connect

n8n

An API key

Surveys Read to connect

Data Studio

An API key

Answers Read and Responses Read

Power BI

A Key (use an API key)

Questions Read and Responses Read

Fivetran

An Account key (use an API key)

Answers Read, Responses Read, Surveys Read and Questions Read

Salesforce Flow

An API key, in Salesforce's Custom Settings

Team members Read, Customers Read and Answers Read, plus Responses Write to send a survey

AI assistants (MCP)

An API key or a Simplesat sign-in. The legacy account key doesn't work here.

The scope for each MCP tool it uses

Integrations on the Integrations page

No key from you

None

Each tool's setup is covered in its own article, such as Zapier integrations.

To connect an AI assistant, see Simplesat MCP integration.

Troubleshooting

A tool is asking for my Account Key

"Account key" is the older name for a Simplesat key, and some tools still use it. Create an API key with the scopes the tool needs and paste it in. Both kinds of key work on every REST path, and an API key is the one you can copy: the full legacy account key isn't shown anywhere in Simplesat.

My new API key gets 403 Invalid credentials

This means the key is mistyped, cut short or deleted. Check that you pasted the whole key, not the start shown on the API keys page. The full key is shown only once, when you create it. If you didn't save it, create a new key and delete the old one.

My key gets 403 You do not have permission to perform this action

The key is Custom and doesn't have the scope for that call. Edit the key and select the scope. The change applies to the next call, and there's nothing to update in the tool.

I get Invalid Token

The value you sent doesn't start with ssat_ and doesn't match any legacy account key. That happens with a legacy account key that's been reset, for example, or with only part of one. Create an API key and use it instead.

I get No API Key Provided

The key wasn't sent in the X-Simplesat-Token header. A key sent as Authorization: Bearer counts as no key, because the API doesn't read that header. AI assistants are the exception: they send the key as Authorization: Bearer.

My key stopped working after a while

Keys don't expire. A key stops working when it's deleted, when a scope it needs is removed, or, for the legacy account key, when it's reset. Check that the key is still on the API keys page, and hover over Custom to see its scopes.

The key in the table is cut off and I can't copy all of it

The table only ever shows the start of a key, and the full key is shown once, when you create it. Create a new key, put it in your tool, then delete the old one.

I can't see the API keys page

The API keys page is open to Owners, Admins and anyone whose custom role includes Access API key. Ask an Owner or Admin to create the key for you, or to give you access.

FAQ

Do API keys expire?

No. A key works until it's deleted.

Can I make a key read-only?

Yes. Choose Custom and select only Read scopes. The legacy account key can't be made read-only.

Can I limit a key to some surveys or teams?

No. A key's scopes cover the whole workspace.

How do I rotate a key?

Create a new key, put it in your tool, then delete the old one. To rotate the legacy account key, contact us to reset it. The old value stops working at once. Move anything that uses it to an API key first.

Does creating an API key replace the legacy account key?

No. Both stay valid. To shut off the legacy account key, contact us to reset it.

Does the legacy account key work with the v1 API?

Yes. Both kinds of key work on the v1 API and on the older paths.

Will the older paths (v0) stop working?

There's no date set to turn them off.

Will the legacy account key stop working?

Not on its own. It works until it's reset. For new code, use an API key and the v1 API (/api/v1/).

How many API keys can I create?

There's no limit. With one key per tool, you can delete any of them without breaking the rest.

Did this answer your question?