***

title: Scopes matrix
subtitle: The current endpoint-to-scope mapping for the live API
slug: scopes-matrix
-------------------

This page summarizes the current scope policy for the public API.

## Live scope requirements

| Endpoint                                                  | Method   | Required scope(s)                               | Conditional scope(s)                                                                                            | Summary                                        |
| --------------------------------------------------------- | -------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `/api/v1/oauth/token`                                     | `POST`   | None                                            | None                                                                                                            | Exchange OAuth credentials for an access token |
| `/api/v2/transcript_comments/{transcript_comment_id}`     | `GET`    | `engagements:read`, `transcript_comments:read`  | None                                                                                                            | Get transcript comment                         |
| `/api/v2/transcript_comments/{transcript_comment_id}`     | `PATCH`  | `engagements:read`, `transcript_comments:write` | None                                                                                                            | Update transcript comment                      |
| `/api/v2/transcript_comments/{transcript_comment_id}`     | `DELETE` | `engagements:read`, `transcript_comments:write` | None                                                                                                            | Delete transcript comment                      |
| `/api/v2/companies`                                       | `GET`    | `companies:read`                                | None                                                                                                            | List companies                                 |
| `/api/v2/companies`                                       | `POST`   | `companies:write`                               | None                                                                                                            | Create company                                 |
| `/api/v2/companies/{company_id}`                          | `GET`    | `companies:read`                                | None                                                                                                            | Get company                                    |
| `/api/v2/companies/{company_id}`                          | `PATCH`  | `companies:write`                               | None                                                                                                            | Update company                                 |
| `/api/v2/companies/{company_id}`                          | `DELETE` | `companies:write`                               | None                                                                                                            | Delete company                                 |
| `/api/v2/companies/{company_id}/crm_association`          | `PUT`    | `companies:write`                               | None                                                                                                            | Set company CRM association                    |
| `/api/v2/companies/{company_id}/crm_association`          | `DELETE` | `companies:write`                               | None                                                                                                            | Clear company CRM association                  |
| `/api/v2/companies/{company_id}/engagements`              | `GET`    | `engagements:read`                              | If `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | List company engagements                       |
| `/api/v2/contacts`                                        | `GET`    | `contacts:read`                                 | None                                                                                                            | List contacts                                  |
| `/api/v2/contacts`                                        | `POST`   | `contacts:write`                                | None                                                                                                            | Create contact                                 |
| `/api/v2/contacts/{contact_id}`                           | `GET`    | `contacts:read`                                 | None                                                                                                            | Get contact                                    |
| `/api/v2/contacts/{contact_id}`                           | `PATCH`  | `contacts:write`                                | None                                                                                                            | Update contact                                 |
| `/api/v2/contacts/{contact_id}`                           | `DELETE` | `contacts:write`                                | None                                                                                                            | Delete contact                                 |
| `/api/v2/contacts/{contact_id}/crm_association`           | `PUT`    | `contacts:write`                                | None                                                                                                            | Set contact CRM association                    |
| `/api/v2/contacts/{contact_id}/crm_association`           | `DELETE` | `contacts:write`                                | None                                                                                                            | Clear contact CRM association                  |
| `/api/v2/contacts/{contact_id}/engagements`               | `GET`    | `engagements:read`                              | If `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | List contact engagements                       |
| `/api/v2/engagements`                                     | `GET`    | `engagements:read`                              | If `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | List engagements                               |
| `/api/v2/engagements/{engagement_id}`                     | `GET`    | `engagements:read`                              | If `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | Get engagement                                 |
| `/api/v2/engagements/{engagement_id}/transcript_comments` | `GET`    | `engagements:read`, `transcript_comments:read`  | None                                                                                                            | List engagement transcript comments            |
| `/api/v2/engagements/{engagement_id}/transcript_comments` | `POST`   | `engagements:read`, `transcript_comments:write` | None                                                                                                            | Create engagement transcript comment           |
| `/api/v2/engagements/{engagement_id}/contacts`            | `PUT`    | `engagements:write`                             | None                                                                                                            | Replace engagement contacts                    |
| `/api/v2/engagements/{engagement_id}/tags`                | `PUT`    | `engagements:write`                             | None                                                                                                            | Replace engagement tags                        |
| `/api/v2/engagements/{engagement_id}/transcript_timeline` | `GET`    | `transcript_timelines:read`                     | None                                                                                                            | Get engagement transcript timeline             |
| `/api/v2/tags`                                            | `GET`    | `tags:read`                                     | None                                                                                                            | List tags                                      |
| `/api/v2/tags`                                            | `POST`   | `tags:write`                                    | None                                                                                                            | Create tag                                     |
| `/api/v2/tags/{tag_id}`                                   | `GET`    | `tags:read`                                     | None                                                                                                            | Get tag                                        |
| `/api/v2/tags/{tag_id}`                                   | `PATCH`  | `tags:write`                                    | None                                                                                                            | Update tag                                     |
| `/api/v2/tags/{tag_id}`                                   | `DELETE` | `tags:write`                                    | None                                                                                                            | Delete tag                                     |
| `/api/v2/users`                                           | `GET`    | `users:read`                                    | None                                                                                                            | List users                                     |
| `/api/v2/users/{user_id}`                                 | `GET`    | `users:read`                                    | None                                                                                                            | Get user                                       |

## Notes

* A valid credential without the route's required or conditional scope returns `403`.
* `workspace:admin` can be used for full access across the current public API surface.
* Engagement reads with `expand=companies`, `expand=contacts`, or `expand=owner` require the additional scopes shown above.