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

# Scopes

> Permissions that control what each PSNTools API key is allowed to do.

<Note>
  Placeholder. The API is not live yet and the scope names below are illustrative, not final.
</Note>

Scopes limit what a key can do. You pick them when creating a key, and a request that needs a scope the key doesn't hold returns `403`.

## Available scopes

| Scope            | Grants                                                 |
| ---------------- | ------------------------------------------------------ |
| `account:read`   | Look up public account data — online ID, region, level |
| `trophy:read`    | Read trophy lists and trophy levels                    |
| `avatar:read`    | Search the avatar catalogue and read avatar metadata   |
| `avatar:write`   | Add and activate avatars on the authenticated account  |
| `profile:write`  | Modify the authenticated account's profile             |
| `analytics:read` | Read the authenticated account's purchase history      |

## Requesting scopes

Scopes are attached to the key, not to the individual request — there is no per-call scope parameter.

```bash theme={null}
curl https://api.psntools.com/v1/keys \
  -H "Authorization: Bearer psn_live_xxxxxxxxxxxx" \
  -d '{ "scopes": ["account:read", "trophy:read"] }'
```

## Least privilege

<Warning>
  Write scopes like `profile:write` and `avatar:write` change the account they act on. Only grant them to a key that actually needs them, and keep read-only integrations on read-only keys.
</Warning>

## Scopes and membership tiers

Some scopes will only be available on higher membership tiers, mirroring what each tier unlocks on the website.


## Related topics

- [PSNTools API](/api/overview.md)
- [Authentication](/api/authentication.md)