Skip to main content

​
Sending your key

Send the key in the Authorization header of every request:
A key from the live Scoutworks starts with sw_live_. A key from the demo or staging starts with sw_test_, so you can tell from the key alone that it cannot read real data. A key belongs to one group and reads only that group’s data. The API never takes a group ID from the URL. A district, county, region or the national team has its own kind of key, which reads totals for the groups below it: see Keys for districts and above.
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 district or area key has its own two scopes. They read the node endpoints only, and a group key cannot hold them: A task key reaches every board in your group, including restricted boards and the trustee duties board, whoever created the key. A change is recorded as made by the admin who created the key. Scoutworks also marks the task with the key’s name, so the group can see a script added or changed it. Give each key a name people will recognise, for example “Grants bot”. A write needs the group’s subscription to be active; reads do not. 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 (for a district or area key, an admin of the district or area).
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. When that happens, the 401 message says the key is from the other server.