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

# Scopes

> Every scope a company admin can grant your App

A company admin grants scopes on the OAuth consent screen. Your token can
only do what its granted scopes allow; an endpoint that needs a scope you
don't have returns `403 missing_scope`.

## Available now

| Scope | Grants |
| - | - |
| `users:read` | `GET /v1/users`, `GET /v1/users/{id}`: id, name, display name, avatar, title, timezone, `is_active`, `is_bot`, `is_admin`, `is_external` |
| `users:read.email` | Adds `email` to user objects (subject to each person's visibility setting), and enables `GET /v1/users/lookup` |
| `conversations:read` | `GET /v1/conversations`, `GET /v1/conversations/{id}`: groups and named channels your bot is a member of |
| `conversations:history` | `GET /v1/conversations/{conversation_id}/messages`: message history your bot can see |
| `files:read` | `GET /v1/conversations/{conversation_id}/files/{id}`: file metadata and a download link, through a message your bot can read |
| `messages:write` | `POST /v1/messages`, and editing or deleting your bot's own messages |

## Notes

* `email` is never returned without `users:read.email`, and even then only
  when the person's email visibility allows it. A withheld email is
  indistinguishable from no match on `GET /v1/users/lookup` — both return
  `404 user_not_found`.
* Phone numbers are never returned by any scope.
* There's no scope for reading a bot's own messages back beyond what
  `POST /v1/messages` and `PATCH /v1/messages/{id}` already return —
  message history read is `conversations:history`, above.