Skip to main content

​
Sending your key

Send the key in the Authorization header of every request:
Every key starts with sw_live_. A key belongs to one group and reads only that group’s data. The API never takes a group ID from the URL.
Treat a key like a password. Keep it in your tool’s secret store (for example Script Properties in Google Sheets, or Credentials in n8n). Never put it in a cell, a shared document or a public repository.

​
Scopes

A scope opens one area of your group’s data. When you create a key, choose only what the key needs. A .contacts scope adds fields to responses you can already read. It does nothing on its own, so you must also choose its area scope. A field that your key may not see is left out of the response. It is not sent as null. So check whether a field exists before you read it. The API never shares health information, bank details or free-text notes, whatever the scopes. If a key calls an endpoint without the right scope, the API answers 403 with the code insufficient_scope. A group admin can add a scope to an existing key in Settings → Integrations → API keys → Edit. The key itself does not change.

​
When a key stops working

A key stops working when:
  • a group admin revokes it;
  • it reaches its expiry date (a key with expiresAt: null never expires); or
  • the admin who created it is no longer an active group admin of the group.
The last one catches people out. If the admin who made the key steps down, the key stops. It works again if they become a group admin again. To avoid this, a current admin can create a new key. A key that stops working gets 401 with the code invalid_api_key.

​
Check a key

GET /me tells you which group and scopes a key has. It needs no scope, so it is the best first call. It also says when the key expires (expiresAt, or null if it never does) and which Scoutworks answered (environment: production, staging, demo or development). A key works only where it was created, so a live key gets 401 on the demo server, and the sandbox key gets 401 on the live one.