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

# Keys and scopes

> How to send a key, what each scope unlocks, and when a key stops working.

## Sending your key

Send the key in the `Authorization` header of every request:

```text theme={null}
Authorization: Bearer sw_live_…
```

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.

<Warning>
  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.
</Warning>

## Scopes

A scope opens one area of your group’s data. When you create a key, choose only what the key needs.

| Scope                        | What it gives                                                        |
| ---------------------------- | -------------------------------------------------------------------- |
| `members:read`               | Members: names, sections, patrols and status.                        |
| `members.contacts:read`      | Adds dates of birth and parent names and emails to members.          |
| `events:read`                | Events, and who is going to each one.                                |
| `badges:read`                | Badge progress and awards.                                           |
| `waiting-list:read`          | The waiting list: names, sections, status and position.              |
| `waiting-list.contacts:read` | Adds dates of birth and parent names and emails to the waiting list. |

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.

```bash theme={null}
curl https://api-demo.scoutworks.app/api/v1/me \
  -H "Authorization: Bearer sw_live_473adcc6c7236916021f0f24559db36576a53bab071d0f0c08a025adb510b6ab"
```