Authentication and API keys

Every request to the API carries an API key as a bearer token:

curl "$SF_API/v1/me" -H "Authorization: Bearer $SF_KEY"

There are no sessions, cookies or refresh tokens. A key works until it expires, is revoked, or loses the access it was created with.

Create a key

Owners and admins of an organization create keys in the dashboard under Settings → API keys. A key has:

• a name, so people know what uses it, for example "Reservations sync (production)"
• one or more scopes, which decide what it can do
• optionally a venue, which limits it to that venue's surveys
• optionally an expiry of 1 to 3650 days; without one it never expires

The token is shown once, right after you create the key.

An API key can't create other keys. Otherwise one leaked key could create new keys that revoking it wouldn't remove.

Token format

sfk_live_V1StGXR8Z5jd_<43-character secret>

The parts are sfk, the environment (live in production, test elsewhere), a 12-character public prefix and the secret. The prefix is safe to log and is what the dashboard shows in the key list; the secret is not. The environment marker only helps people tell where a leaked token came from. Nothing checks it.

Scopes

:write does not include :read. A key that needs both gets both. An integration that only pushes surveys shouldn't be able to read what respondents answered.

Give each integration its own key with the fewest scopes it needs. When a call needs a scope the key lacks, it answers 403 INSUFFICIENT_SCOPE and names the missing scope in details.requiredScope.

To change a key's scopes or venue later, use Change permissions next to the key. The token stays the same and the new scopes apply from its next request. Only a live key can be changed, not a revoked or expired one.

Keys for one venue

A key created for a venue only reaches that venue. Lists leave out the other venues' surveys, a survey of another venue answers 403, and a survey created without venueId goes to the key's venue. Use venue keys when an integration belongs to one location, for example a single shop's till.

Check a key

GET /v1/me needs no scope and describes the key:

{
  "organizationId": "934c6a69-ed8e-4110-ba37-644a84047341",
  "tier": "BUSINESS",
  "scopes": ["surveys:read", "responses:read"],
  "venueId": null,
  "prefix": "V1StGXR8Z5jd"
}

It is the quickest way to tell a wrong token (401) from a missing scope or plan (403).

A key acts for the person who created it

A key carries the permissions of the member who created it, checked again on every request:

• If their role is reduced, the key is reduced with it at once. A key created by an owner who is now a viewer can read but no longer write.
• If they leave the organization, or their account is suspended or deleted, the key stops working with 401 API_KEY_REVOKED.
• If a venue key's creator loses access to that venue, or an organization-wide key's creator keeps only venue roles, the key stops working the same way.

Leaving, suspension and deletion also revoke the key for good. Adding the person back or reactivating the account doesn't bring the key back; create a new one.

An owner or admin can create keys, which is worth knowing before you make someone an admin: a key works outside the dashboard for whoever holds the token. It can never do more than its creator, though, and owners and admins see and can revoke every key of the organization.

Revoke a key

Revoke a key in Settings → API keys. Its next request answers 401 API_KEY_REVOKED. Creating, changing and revoking keys is recorded in the organization's audit log with the prefix, never the token.

Password changes

Changing or resetting a password signs the account out everywhere but leaves its API keys alone, so a routine password change doesn't take your integrations offline.

If you reset the password because someone else may have been in the account, also revoke the keys they might have created in Settings → API keys, and create new ones for your integrations.

Plan and organization

On top of the key itself, every request needs:

• an active organization, otherwise 403 ORG_SUSPENDED
• a plan with API access, otherwise 403 API_ACCESS_NOT_IN_TIER

Both are checked on every request, so changes take effect immediately. The order of all checks is in Errors.