> ## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.