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

# Scopes

> All 12 OAuth2 scopes, what each one grants, and common combinations for different integration types.

Scopes define exactly what your app can do on a user's behalf. Busha has a flat allowlist of 12 scopes. Anything outside this list is rejected at registration with `invalid_scope`.

**Request only what your integration needs.** Users see your scope list on the consent screen — asking for more depresses conversion. Users can only Approve or Cancel the full bundle; they cannot cherry-pick individual scopes.

Admin approves your partner client overall (not per scope). After approval, `approved_scopes = requested_scopes`.

## Identity scopes

These are protocol-level scopes. Busha hides them from the consent screen, but they control whether you receive an `id_token` and a `refresh_token`. Request them if you want those tokens.

| Scope            | What it grants                                                                                                               |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `openid`         | OIDC marker. Required for `id_token` issuance.                                                                               |
| `offline_access` | Required for `refresh_token` issuance. Without it, the access token expires after one hour with no way to renew the session. |

## Wallets and balances

| Scope               | What it grants                                      |
| ------------------- | --------------------------------------------------- |
| `balances:read`     | List the user's wallets and their current balances. |
| `transactions:read` | Read the user's transaction history.                |

## Trading

| Scope          | What it grants                                                                          |
| -------------- | --------------------------------------------------------------------------------------- |
| `quotes:read`  | Read price quotes. No rate commitment.                                                  |
| `quotes:write` | Lock a price quote. **This commits the partner to the rate — treat as money movement.** |

## Transfers

| Scope             | What it grants                                                             |
| ----------------- | -------------------------------------------------------------------------- |
| `transfers:read`  | Read the user's transfer history.                                          |
| `transfers:write` | Initiate outgoing transfers on the user's behalf. **Real money movement.** |

## Wallet addresses

| Scope             | What it grants                                     |
| ----------------- | -------------------------------------------------- |
| `addresses:read`  | Read the user's existing wallet deposit addresses. |
| `addresses:write` | Generate new deposit addresses for the user.       |

## Recipients

| Scope              | What it grants                                                |
| ------------------ | ------------------------------------------------------------- |
| `recipients:read`  | Read the user's saved transfer recipients.                    |
| `recipients:write` | Add, update, or delete saved recipients on the user's behalf. |

## Common combinations

| Integration type              | Recommended scopes                                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Read-only portfolio dashboard | `openid offline_access balances:read transactions:read`                                                                 |
| Deposit flow                  | `openid offline_access balances:read addresses:read addresses:write`                                                    |
| Outbound transfers            | `openid offline_access balances:read transactions:read recipients:read recipients:write transfers:read transfers:write` |
| FX / trading widget           | `openid offline_access balances:read quotes:read quotes:write`                                                          |

<Note>
  Always include `openid` and `offline_access` in production integrations unless you deliberately want a single-session, one-hour token with no refresh capability.
</Note>