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

# OAuth Scopes and What They Grant

> The Trench Partner API scope registry, exactly which endpoint each scope gates, and why governance reads require no scope at all.

Scopes are sent space-separated in the authorize URL and echoed back in the token response. We recommend requesting only the scopes your integration needs, since each one is shown to the user on the consent screen and high-risk scopes are flagged.

## The Registry

| Scope                | Grants                                       | Risk |
| -------------------- | -------------------------------------------- | ---- |
| `profile:read`       | Wallet address, X handle, trading status     | Low  |
| `trade:execute`      | Buys and sells                               | High |
| `governance:vote`    | Vote, cancel, withdraw locked tokens, settle | High |
| `governance:propose` | Create proposals, withdraw bonds             | High |

<Note>
  Three further scopes exist in the authorization server, `positions:read`, `social:read`, and `social:write`, but they are hidden and cannot be selected when you register an app. Nothing in the API gates on them yet, so offering them would promise access that does not exist. Grants that already carry one continue to work.
</Note>

## Endpoint to Scope Map

| Endpoint                                                  | Scope                |
| --------------------------------------------------------- | -------------------- |
| `GET /partner/v1/me`                                      | `profile:read`       |
| `POST /partner/v1/trades/buy`                             | `trade:execute`      |
| `POST /partner/v1/trades/buy-exact-out`                   | `trade:execute`      |
| `POST /partner/v1/trades/sell`                            | `trade:execute`      |
| `POST /partner/v1/governance/votes`                       | `governance:vote`    |
| `POST /partner/v1/governance/votes/cancel`                | `governance:vote`    |
| `POST /partner/v1/governance/votes/withdraw`              | `governance:vote`    |
| `POST /partner/v1/governance/proposals/settle`            | `governance:vote`    |
| `POST /partner/v1/governance/proposals/update-content`    | `governance:propose` |
| `POST /partner/v1/governance/proposals/extend-mutability` | `governance:propose` |
| `POST /partner/v1/governance/proposals/finalize-metadata` | `governance:propose` |
| `POST /partner/v1/governance/metadata/finalize-expired`   | `governance:propose` |
| `POST /partner/v1/governance/bonds/withdraw`              | `governance:propose` |

Two of these groupings are not obvious from the scope names. Settling a proposal is gated by `governance:vote` rather than `governance:propose`, because settling closes a finished vote. Withdrawing a bond and finalizing expired metadata are both gated by `governance:propose`, even though neither creates a proposal.

## Reads Require No Scope

The following endpoints mirror public on-chain state, so any valid access token may call them.

* `GET /partner/v1/governance/{mint}`
* `GET /partner/v1/governance/proposals/{proposal}/votes`

<Tip>
  `GET /partner/v1/governance/{mint}` includes a `viewerVotes` array containing the connected user's own votes, derived from the access token. You get these without a scope and without making a second request.
</Tip>

## Requesting Scopes

Scopes are passed space-separated in the authorize URL.

```text theme={null}
scope=profile:read trade:execute governance:vote
```

The server splits on whitespace or `+`. A single unknown scope will fail the entire string.

| Error                | Cause                                                            |
| -------------------- | ---------------------------------------------------------------- |
| `invalid_scope`      | The string is empty or contains a scope not in the registry      |
| `scope_not_allowed`  | The scope exists, but your app did not select it at registration |
| `insufficient_scope` | You called an endpoint whose scope you did not request           |

A `403 insufficient_scope` response names the scope you need in its `message` field.

## Widening a Grant

An existing token cannot be widened. To request additional scopes, send the user back through the authorize flow with the wider set and exchange the new code.

<Note>
  Re-consenting merges scopes on the underlying grant, but each access token only carries the scopes from the code that produced it. Make sure you use the newly issued token, since the previous one keeps its narrower set until it expires.
</Note>