> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate to the Statisfy API with a scoped API key, choose the scopes a key needs, and keep keys safe.

Every request to the Statisfy API carries an API key as a bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.statisfy.com/v1/meta/whoami \
  -H "Authorization: Bearer $STATISFY_API_KEY"
```

Keys start with `stfy_live_`. A request without a valid key returns `401` with the error code `unauthorized`.

## What an API key is

* **It belongs to your workspace, not to a person.** A key isn't tied to the admin who created it. It works across your whole workspace, limited only by its scopes.
* **It has a name.** The name identifies the integration that uses the key, such as `HubSpot sync` or `Nightly renewal script`. No two active keys in a workspace share a name.
* **It has scopes.** A key can only call the operations its scopes allow. See [Scopes](#scopes).
* **It's shown once.** Statisfy shows the full key only when it's created and doesn't keep a readable copy, so a lost key can't be recovered. Create a new one and revoke the old one instead.
* **It can expire.** A key can have an expiry date, after which requests with it return `401`. A key without one works until it's revoked.
* **It can be revoked.** Revocation takes effect immediately and can't be undone.

## Get an API key

Admins create keys in Statisfy, in **Settings → API Keys**.

1. Click **Create key**.
2. **Name** the key after the integration that will use it, such as `HubSpot sync`.
3. Under **Access**, choose what the key can do on each object: **View**, **Create**, **Edit**, or **Delete**, or, for objects that take one verb for every change (such as product usage, email templates, and activities), **Write**. Choosing anything other than View includes View. **Access** lists only the objects your workspace's plan includes. **Full access** grants every scope your plan includes; avoid it unless an integration truly needs everything.
4. Choose when the key **Expires**: never, or in 30 days, 90 days, or 1 year.
5. Click **Create key**, then copy the key and store it somewhere safe, such as a secrets manager. This is the only time the full key is shown.

**Settings → API Keys** lists every key that hasn't been revoked, with its access, when it was created and last used, and when it expires. An expired key stays in the list, marked **Expired**, until you revoke it. It shows only the start of each key, never the whole key.

To confirm the key works and see its scopes, call `GET /v1/meta/whoami`. See the [quickstart](https://help.statisfy.com/rest-api/overview.md#quickstart).

## Scopes

A scope has the form `<object>:<verb>`.

| Object | Scopes |
| - | - |
| Accounts | `accounts:read`, `accounts:create`, `accounts:update`, `accounts:delete` |
| Contacts | `contacts:read`, `contacts:create`, `contacts:update` |
| Custom objects' records | `custom_objects:read`, `custom_objects:create`, `custom_objects:update`, `custom_objects:delete` |
| Account health (each pillar's reason, confidence, source, and history) | `health:read` |
| Meetings (recorded by Statisfy's notetaker) | `meetings:read` |
| Meeting transcripts (download links) | `transcripts:read` |
| Clips: parts of a recording, cut from any recorder's meetings and calls | `clips:read`, `clips:create`, `clips:update`, `clips:delete`, `clips:share` |
| The customer timeline: activities of every kind, with their AI summaries; and what your other systems push onto it | `activities:read`, `activities:write` |
| What was written in an activity: a thread's messages, a note, a survey's answers, a campaign's email | `activity_content:read` |
| Conversations your AI handles, with their messages and internal notes | `conversations:read` |
| Opportunities | `opportunities:read`, `opportunities:create`, `opportunities:update`, `opportunities:delete` |
| Saved views and segments of the Accounts, People, and Opportunities pages | `views:read`, `views:update` |
| Products and their usage dimensions | `products:read`, `products:create`, `products:update`, `products:delete` |
| Product usage values | `usage:read`, `usage:write` |
| Projects and project templates | `projects:read`, `projects:create`, `projects:update`, `projects:delete` |
| Reports, their widgets, and report SQL | `reports:read`, `reports:create`, `reports:update`, `reports:delete` |
| Email templates and their merge tags | `templates:read`, `templates:write` |
| Surveys and their responses | `surveys:read`, `surveys:create`, `surveys:update`, `surveys:delete` |
| Campaigns, their audiences, and what they sent | `campaigns:read`, `campaigns:write`, `campaigns:publish` |
| Digital workers, the accounts they cover, and their proactive tasks | `digital_workers:read`, `digital_workers:create`, `digital_workers:update`, `digital_workers:activate`, `digital_workers:evaluate` |
| Emails your digital workers sent on their own initiative, with their words and what became of them | `outreach:read` |
| Knowledge bases: the documents your digital workers and Stella answer from, with their words, and a search that finds what a worker would | `knowledge:read`, `knowledge:write` |
| Skills: the instructions your agents load when they need them, Statisfy's and your own | `skills:read`, `skills:write`, `skills:publish` |
| Users: your teammates and their custom user fields | `users:read`, `users:update` |
| AI credits: the summary, usage by flow, and the usage log | `credits:read` |
| Tasks | `tasks:read`, `tasks:create`, `tasks:update`, `tasks:delete` |
| Comments on tasks and projects, with their @mentions | `comments:read`, `comments:create`, `comments:update`, `comments:delete` |
| Field definitions | `fields:read`, `fields:create`, `fields:update`, `fields:delete` |
| Sender domains: the domains your workspace sends email from, and their DNS records | `sender_domains:read`, `sender_domains:create`, `sender_domains:delete` |
| Notification rules: who gets a processed meeting's insights, and when | `notification_rules:read`, `notification_rules:create`, `notification_rules:update`, `notification_rules:delete` |
| Workspace settings: the settings of Settings > Config that the API covers; and, read only, the workspace's licenses and features, health settings, renewal settings, CRM write-back settings, and Company Context | `settings:read`, `settings:update` |
| Audit logs: who changed which record, when, and through which surface | `audit_logs:read` |
| Integrations: every app your workspace can connect, with its connections, schedule, runs, and Slack or Teams channels; file imports and their feeds; a SQL warehouse's config, saved queries, and SQL run against it; and Pendo's config, queries, survey settings, schedule, and lookups | `integrations:read`, `integrations:write` |
| Agent Studio: agents, and flows with their steps | `agent_studio:read` |
| Workflows: questions Stella answers on a schedule | `workflows:read` |
| Approvals: the flow runs waiting on an Agent Studio approval step, with what they would send | `approvals:read`, `approvals:write` |
| Everything | `admin` |

The two meeting scopes are separate. `transcripts:read` gets a meeting's transcript links and its participants (names and emails included) but doesn't list meetings, and `meetings:read` doesn't get transcripts. To find meetings and download their transcripts, grant both.

`activity_content:read` is separate from `activities:read`. `activities:read` lists the timeline and gets each activity's AI summary and the facts of its kind (a ticket's status, a survey's score, a campaign). `activity_content:read` reads what was written in an activity: email, chat, ticket, and Chatter messages (bodies, senders, recipients, attachment names), notes, survey answers, and campaign emails. It covers every account, so grant it only to an integration that may read all of the workspace's mail, chats, notes, and survey answers. Neither shows a meeting's transcript: that is `transcripts:read`, for meetings Statisfy's notetaker recorded.

`activities:write` pushes what another of your systems (a marketing platform, a sequencer) did with a person, such as an email thread, a LinkedIn conversation, a call, or a form, onto their account's timeline. It writes and deletes only what was pushed through the API, never an activity Statisfy synced. Like every write scope, it also reads: a key with it can list the timeline as `activities:read` does. A key that acts for a person gets it only when that person is an admin.

`conversations:read` reads a conversation whole: its record, its thread's messages (bodies, senders, recipients, attachment names), and its internal notes. It needs neither timeline scope, and covers every conversation the workspace's plan includes, so grant it only to an integration that may read them all. AI drafts nobody has sent are never on the API.

What each verb allows:

| Verb | Allows |
| - | - |
| `read` | List, search, and get records. For fields, list and get field definitions. |
| `create` | Create records. For fields, create custom fields. |
| `update` | Update records one at a time or in a batch. For fields, change a field's display name, visibility, requiredness, and picklist options. |
| `delete` | Delete records. For fields, delete a custom field and its values. |
| `write` | For product usage, write and delete usage values. For email templates, create, change, publish, and delete them. For campaigns, create, change a draft, unpublish, delete a draft, and send a test email. For skills, create and copy skills, and change, make an earlier version live, or archive one no agent uses. For integrations, save a SQL warehouse's config, queries, and schedule, start runs, and run or preview SQL against the warehouse; for Pendo, save its config, queries, survey settings, and schedule, start runs, and preview a query and the survey job, which return Pendo data; and create, change, test, run, and delete file import feeds. For activities, push what another system did with a person (create or update it) and delete what was pushed. |
| `publish` | For campaigns, publish a campaign and change a published one. Publishing sends email to your customers. For skills, change, make an earlier version live, or archive a skill an agent uses. The change reaches those agents at once. |
| `activate` | For digital workers, activate a worker and change an active one. An active worker answers your customers and writes to them. |
| `share` | For clips, open a clip's public page. Anyone with the link can watch the clip. |

How scopes combine:

* **A key reaches only what your workspace's plan includes, whatever its scopes**, **Full access** included. A call to an object your plan doesn't include returns `403` with the code `not_entitled`. When your plan changes, your keys follow on their next call.
* **Every write verb includes `read`** on the same object. A key with `tasks:update` can also list and get tasks.
* **Write verbs don't include each other.** A key with `opportunities:update` can't create or delete opportunities.
* **Upserts need both `create` and `update`** on the object, because an upsert can do either.
* **Account records carry each health pillar's current label, and the overall reason (`health_summary`), with `accounts:read`.** Each pillar's reason, confidence, source, and history need `health:read`.
* **Product usage needs only a `usage` scope, but finding a product's id and its dimension keys needs `products:read`.**
* **`reports:read` reads everything your report views hold, whatever other scopes the key has**: accounts and their fields, contacts, your team's names and emails, opportunities, account owners, health, product usage, tasks, activities, projects, surveys, support tickets, custom objects, and Digital Worker conversations (subjects and participants) and actions. It also lists every report, private ones included, with its owner's email. Grant it only to an integration that may read all of that.
* **A report's widgets go by the same verbs as the report.** Adding a widget needs `reports:create`, changing one `reports:update`, and deleting one `reports:delete`.
* **Each `reports` write scope includes `reports:read`**, so it reads everything the report views hold too. It can also change or delete any report, private ones included, whoever owns it: the app's rule that only a report's owner or an admin changes it doesn't apply to API keys.
* **`templates:write` can change or delete any email template except a survey's, published ones included.** Campaigns and Agent Studio flows read a template each time they send, draft or published, so a change goes out on their next send, as an edit in the app does.
* **Previewing a template with a real contact needs `contacts:read`, and with a real account `accounts:read`**, as well as `templates:read`, because the preview shows their field values. A contact's own account renders with real values only when the key has `accounts:read`, and with sample values otherwise. A preview with sample values needs only `templates:read`.
* **Publishing a survey needs `surveys:update`, and it can't be undone.** A published survey can't be changed or deleted. Duplicating it needs `surveys:create`.
* **`surveys:read` lists every response a survey collected**, with the id of the contact who answered.
* **Publishing a campaign needs `campaigns:publish`, and no other scope includes it.** Publishing sends email to your customers, so grant it by name, only to an integration that may send. Changing a published campaign needs it too, because a change changes what is sent. `campaigns:publish` doesn't include `campaigns:read` or `campaigns:write`: grant those as well.
* **`campaigns:write` can unpublish any campaign**, so a key that edits campaigns can always stop a send.
* **A test email goes only to a member of your workspace.** The merge tags can be filled in from any existing contact.
* **`campaigns:read` lists the contacts a campaign was sent to**, with their emails and delivery status.
* **Activating a digital worker needs `digital_workers:activate`, and no other scope includes it.** An active worker answers your customers, and where its replies don't wait for a person it writes to them on its own, following its job, voice, and guardrails. Changing an active worker needs it too, because a change changes what the worker tells your customers. Grant it by name, only to an integration that may put a worker in front of your customers. It doesn't include the other `digital_workers` scopes: grant those as well.
* **`digital_workers:update` can stop or archive any worker**, so a key that edits workers can always take one off the air.
* **`digital_workers:evaluate` tries a worker without changing it.** A preview of one message (`POST /v1/digital_workers/{worker_id}/preview`) and an evaluation run work on a copy of the worker: they send nothing and save nothing, so a key that may test a worker needn't be one that may change it. Restoring a saved version is a change: it needs what a `PATCH` needs.
* **`digital_workers:update` adds, changes, and deletes a worker's proactive tasks**: the work it does on its own, once, on a schedule, or until a goal is met. It doesn't need `digital_workers:activate`, even for a worker whose outreach is on, so a key with it can give a worker that writes to your customers new work. Adding or changing a task needs AI CSM; closing or deleting one doesn't, so a key that edits workers can always stop a task. A digital worker's own key reads tasks but never writes them.
* **`outreach:read` reads every email your digital workers sent on their own initiative**: its words, who it went to, and what became of it (the customer's reply, its delivery, opens and clicks, an opt-out). It needs no other scope, so grant it only to an integration that may read all of that email.
* **`knowledge:read` reads every knowledge base and its documents, words included**, whatever their account, and searches them as a worker would. It needs no other scope.
* **`knowledge:write` adds, changes and deletes documents, and makes, changes and deletes knowledge bases.** It writes into knowledge bases it made and ones that take uploads in the app; a connector's are read-only, because its sync would overwrite them. Your digital workers answer your customers from what it writes, so grant it only to an integration that may decide what they say. A digital worker's own key never writes knowledge.
* **`skills:read` reads every skill your workspace can see, instructions and files included**, Statisfy's and your own. It needs no other scope.
* **Changing a skill an agent uses needs `skills:publish`, and no other scope includes it.** A skill is instructions your agents follow, and a change reaches every agent that uses it at once: Stella, the workbench agent, your digital workers, and Agent Studio agents. Grant it by name, only to an integration that may decide what your agents do. `skills:write` alone creates and copies skills and changes ones no agent uses. `skills:publish` doesn't include `skills:read` or `skills:write`: grant those as well. A digital worker's own key never writes skills.
* **The API writes a skill's text files under `references/` only.** Scripts and other files are added in the app, and a skill with tools of its own can only be turned on or off through the API.
* **`sender_domains:create` adds a domain and verifies it.** Only a verified domain can be a campaign's or a flow's From address, so grant it only to an integration that may set up who your workspace sends email as. In the app, only admins manage sender domains.
* **`notification_rules:create` and `notification_rules:update` choose who gets meeting insights.** A rule sends a processed meeting's insights to its recipients. A new email must belong to a member of your workspace, so a rule never sends insights outside it. In the app, every member can manage notification rules.
* **`clips:read` reads parts of recordings.** A clip's video and its `transcript_snippet` hold the words spoken in it, so `clips:read` reads them without `meetings:read` or `transcripts:read`. It covers every clip in the workspace, whoever made it.
* **Sharing a clip needs `clips:share`, and no other scope includes it.** A share opens a public page: anyone with the link can watch the clip, with no login. Grant it by name, only to an integration that may make recordings public. It doesn't include `clips:read`: grant that as well.
* **`settings:update` changes workspace-wide settings.** For example, it can stop the NoteTaker for the whole workspace, change when AI tasks close, or change which senders count as automated. In the app, only people who manage settings change them. It can't change company domains or Stella's PII guardrail.
* **`settings:read` also reads your licenses and features.** `GET /v1/settings/licenses` lists the Statisfy products your workspace has, with each one's term, status, and seats. `GET /v1/settings/licenses/{license_id}/users` lists who holds a seat on a license. `GET /v1/settings/features` lists the app's optional features and whether each is on. These are read only: `settings:update` doesn't change them.
* **`agent_studio:read` reads Agent Studio's agents and flows.** `GET /v1/agents` and `GET /v1/agents/{agent_id}` return each agent with its instructions, toolkits, skills, and knowledge bases, Statisfy's and your own. `GET /v1/automations/flows` and `GET /v1/automations/flows/{flow_id}` return each flow with its trigger and steps. It reads only: the API doesn't create, change, or run agents or flows.
* **`workflows:read` reads scheduled workflows**: the questions Stella answers on a schedule, from the app's Workflows page. It covers `GET /v1/automations/workflows` and `GET /v1/automations/workflows/{workflow_id}`. A key that acts for a person sees only that person's workflows, and another person's workflow returns `404`. Any other key sees every workflow in the workspace.
* **`approvals:read` reads the Approvals inbox**: the flow runs waiting on an Agent Studio approval step, with what each would send (an email's recipients, subject, and body). `GET /v1/approvals` lists them as the app's Approvals page does: `list` is its My Approvals / All Approvals selector, and `status` its tabs (`pending`, `approved`, `rejected`, `history`, or `all`; pending by default). `GET /v1/approvals/{approval_id}` opens one. A key that acts for a person lists My Approvals, and All Approvals only when the person builds in Agent Studio. Any other key lists All Approvals.
* **Only a person decides an approval, with their own key.** `approvals:write` approves or rejects up to 100 approvals at once (`POST /v1/approvals/decisions` with `approval_ids` and `approved`), as the app does for one or many, as the person who made the key, and only approvals assigned to them unless they build in Agent Studio. Any other key gets `403`. Approving resumes each run, which can send email to your customers. Each approval answers on its own: one someone already decided fails with `conflict`, and the others are still decided.
* **`credits:read` reads your AI credit summary, usage by flow, and usage log.** The log names the person who made a call by id only. It never shows a call's prompt or answer.
* **`users:update` can change any teammate's name, role, department, manager, calendar link, and custom user fields.** In the app, only an admin edits another user on the Team page. It can't change a user's access role or membership, or invite anyone.
* **A comment the API writes is by the person who created the key.** `comments:create` posts as that person: the people a task comment mentions are emailed, and so are the task's followers. Only a comment's author can edit or delete it, so `comments:update` and `comments:delete` reach only that person's comments.
* **`fields:delete` deletes a custom field and its value on every record, and the delete can't be undone.** `fields:create` and `fields:update` don't include it. In the app, only admins delete fields.
* **Writing custom field values needs the object's scope, not a `fields` scope.** Setting a value under `fields` on an account needs `accounts:update`. The `fields` scopes cover field definitions only.
* **`audit_logs:read` reads your workspace's audit trail**, as Settings > Audit logs shows it: each call on each record, through the app, the API, MCP, an Agent Studio flow, or a file import, with who made it and the fields it stored. It covers `GET /v1/audit-logs` and `POST /v1/audit-logs/search`, and needs no other scope. A key that acts for a person, such as one Claude uses, gets it only when that person is an admin. Reading the trail isn't itself audited.
* **Audit events filter on a fixed set of fields.** `source` (`app`, `rest`, `mcp`, `agent-studio`, `bulk-file`), `actor_type`, `actor_user_id`, `object_type`, `object_id`, `action`, `status`, and `request_id` take `eq`, `neq`, `in`, and `nin`. `action_happened_at` (RFC 3339) takes `gt`, `gte`, `lt`, and `lte`. A search filter nests at most 3 levels deep and holds at most 20 conditions. Events come newest first, and `limit` is at most 200. See [Search with AND and OR](https://help.statisfy.com/rest-api/requests.md#search-with-and-and-or).
* **`integrations:read` reads every app your workspace can connect, not only SQL warehouses.** It covers `GET /v1/integrations` and, for each app, its status, connections, schedule, and runs. For Slack and Teams, it lists the channels Statisfy is in. It also lists file imports (`GET /v1/integrations/imports`): CSV and Excel files uploaded in the app or received by a file feed, with their row counts and up to 20 failed rows. For a SQL warehouse, it reads the config, saved queries, and the schemas, tables, and columns its catalog lists.
* **`integrations:read` never returns a credential, a token, or a row of warehouse data.** For the SQL warehouses and the other apps it reads metadata only. For Pendo it also returns the query text of Pendo reports (filters can hold values, such as an account ID) and the NPS answer count of each guide, but no Pendo rows, emails, or comments. A key that acts for a person gets either `integrations` scope only when that person is an admin.
* **`integrations:read` also covers Pendo's config, saved queries, and lookups.** The lookups are Pendo's reports, its catalog of pages, features, track types, and apps, the account fields, the NPS guides, the answer counts of the guides, and the check of a Sentiment survey ID. They make live calls to Pendo. The Pendo key stays in Statisfy's app: the API never takes or returns it.
* **`integrations:write` saves a warehouse's config, queries, and schedule, and starts runs.** It also runs `POST /v1/integrations/{key}/sql`, which returns up to 1,000 rows, and `POST /v1/integrations/{key}/preview`, a dry run of a query on up to 1,000 rows that writes nothing. Those rows can be anything the warehouse login can read, so grant it only to an integration that may read all of that. For Pendo, the same scope also changes the config, the queries, the NPS survey settings, and the schedule, and starts Pendo runs, including the NPS survey job. A Pendo save runs the same checks as the app's save, and a refusal comes back as a `422` with the app's text. Saving locks each mapped field.
* **`integrations:write` also returns raw Pendo data.** `POST /v1/integrations/pendo/preview` runs a Pendo query and returns up to 100 rows, and `POST /v1/integrations/pendo/surveys/preview` returns NPS responses, with the visitor's email, rating, and comment. Grant it only to an integration that may read all of that.
* **Warehouse credentials never cross the API.** You connect a warehouse in Statisfy's app. The API can't set its credentials and never returns them. `POST /v1/integrations/{key}/connection/test` checks the stored ones.
* **Send `expected_version` to save a warehouse config safely.** Pass the config `version` you read when you change the config or a query. If the config changed since, Statisfy returns `409` with the code `conflict` and writes nothing: read it again. Left out, the change always lands.
* **`/sql` and `/preview` run against your warehouse, so they can fail there.** Each workspace runs only a couple at once on each server. Past that, Statisfy returns `429` with `rate_limited` and `Retry-After`. SQL the warehouse refuses, and a result over 8 MB, return `422` with `validation_failed`. A warehouse that can't be reached returns `502` with `upstream_failed`, and one with no usable connection `409` with `conflict`. The warehouse stops a query at 120 seconds, which returns `504` with `query_timeout`.
* **`integrations:read` also reads your file import feeds.** It covers `GET /v1/integrations/imports/feeds` and each feed, shown one entry per mapped column with the place it goes, such as `account.fields.tier__c` or `usage.12.active_seats`. `GET /v1/integrations/imports/targets` lists every place a column can go, with whether a feed may write it and why not, and the date formats and identifier fields a feed takes. `POST /v1/integrations/imports/sample` reads a sample's columns and first rows, from CSV text you send or from a file Statisfy received.
* **`integrations:write` also sets up and runs your file import feeds.** `POST /v1/integrations/imports/feeds` creates a feed, switched off; `PATCH` and `DELETE` on `/v1/integrations/imports/feeds/{name}` change or delete one. A save runs the same checks as the app's data import settings, and a refused column comes back as a `422` that names each column and why. Saving locks each mapped field, so it is read-only in the app. `POST /v1/integrations/imports/test` is the app's test of a feed on a sample, which writes nothing. `POST /v1/integrations/imports/feeds/{name}/run` imports one file now: a file the feed received, CSV text you send, or an object in an S3 feed's bucket.
* **An email feed that is off keeps the files it receives.** Each one shows in `GET /v1/integrations/imports` with the status `held`, and imports only when you run the feed on it. Switching the feed on imports the files that arrive afterwards. An S3 feed that is off isn't polled: when you switch it on, it imports every file under its prefix that it hasn't imported before.
* **Send `expected_version` to change a feed safely.** Pass the feed's `version` from `GET /v1/integrations/imports/feeds/{name}`. If the feed changed since, Statisfy returns `409` with the code `conflict` and writes nothing. A run on a file Statisfy already imported is a `409` too.
* **Each run counts what each query read and wrote.** `GET /v1/integrations/{key}/runs` returns `counts` for every query that finished: `read`, then each row in exactly one of `written`, `unmatched` (no account or person), `invalid` (dropped by validators), `skipped` (nothing to write), or `failed`. `counts` is null while a run is going and when every query failed.
* **`admin` allows every operation.** Avoid it unless an integration truly needs everything.
* **`GET /v1/meta/whoami` and `GET /v1/meta/capabilities` need no scope.** Any valid key can call them.

A request the key's scopes don't allow returns `403` with the error code `insufficient_scope`, and the message names the scope it needs. Each operation's required scopes are also listed in `GET /v1/meta/capabilities`.

## Rotate a key

1. Create a new key with the same access and a new name. Names must be unique among active keys.
2. Switch your integration to the new key, and confirm it works with `GET /v1/meta/whoami`.
3. Revoke the old key.

## Revoke a key

In **Settings → API Keys**, click **Revoke** next to the key, then confirm. Revoke a key when the integration that uses it is retired, or right away if the key may have leaked. Revocation takes effect immediately: any request made with the key afterwards returns `401`.

## Keep keys safe

> [!WARNING]
>
> An API key can read and change your workspace's data, so treat it like a password.

* Store keys in a secrets manager or an environment variable. Never commit them to source control.
* Use keys only from servers and scripts. Never put a key in a browser app, a mobile app, or anything else you ship to end users.
* Give each integration its own key, so you can revoke one without breaking the others.
* Ask for the fewest scopes that work. A read-only reporting script needs only `read` scopes.
* Set an expiry date on keys for short-lived work, such as a one-off migration.
* Never paste a key into a support ticket, chat, or log. To trace a request, share the `X-Request-Id` from its response instead. See [Request IDs](https://help.statisfy.com/rest-api/requests.md#request-ids).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.