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

# Busha OAuth2

> Let your users connect their Busha accounts to your product — securely, without ever sharing their password.

## What is Busha OAuth2?

Busha OAuth2 is a delegated-authorization protocol that lets your application act on a Busha customer's behalf. After the customer signs in to Busha and consents to the permissions your app requests, your backend receives a short-lived access token. You attach that token to Busha API calls and interact with the customer's account — reading balances, initiating transfers, generating addresses — without ever seeing their password or holding their credentials.

The protocol is standard **OAuth2 authorization-code grant with PKCE-S256**, plus **OpenID Connect** for user identity. The endpoints are RFC-conformant and work with any compliant OAuth2 client library.

<Note>
  If you only need to call Busha as your own business (no end-user involved), use a **partner API key** instead. OAuth2 is purpose-built for cases where a real Busha customer is granting your app access to their account.
</Note>

## Why OAuth2?

When you build a product on top of Busha — a wallet aggregator, an accounting integration, a treasury dashboard — your users already have Busha accounts with funds in them. OAuth2 gives you a safe, auditable way to interact with those accounts:

* **No password sharing.** Your app never sees the user's Busha credentials.
* **Scoped permissions.** You request only what your integration needs. The customer sees exactly what they're granting.
* **Revocable access.** The customer can disconnect your app at any time from their Busha dashboard. You can also revoke programmatically.
* **Short-lived tokens.** Access tokens expire in \~1 hour. Refresh tokens rotate on every use. A leaked token has a bounded blast radius.
* **Industry-standard.** Any OAuth2-compliant library handles the protocol plumbing so you ship faster.

## What you can build

<CardGroup cols={2}>
  <Card title="Portfolio dashboard" icon="chart-line">
    Read balances and transaction history across a user's Busha wallets. Use `balances:read` and `transactions:read`.
  </Card>

  <Card title="Deposit flow" icon="arrow-down-to-line">
    Read existing deposit addresses or generate new ones on the user's behalf. Add `addresses:read` and `addresses:write`.
  </Card>

  <Card title="Outbound transfers" icon="arrow-right-arrow-left">
    Initiate transfers to saved or new recipients. Add `recipients:read`, `recipients:write`, `transfers:read`, and `transfers:write`.
  </Card>

  <Card title="FX / trading widget" icon="arrow-trend-up">
    Read price quotes and lock rates on the user's behalf. Add `quotes:read` and `quotes:write`. Note: locking a quote commits the partner to that rate — treat it as money movement.
  </Card>
</CardGroup>

## How the flow works

Authorization-code with PKCE is a four-leg exchange. The browser never sees a token — tokens are only exchanged server-to-server.

```
Browser              Busha OAuth2 server          Your backend
  |                          |                          |
  |  GET /oauth2/auth        |                          |
  |  (PKCE challenge, state) |                          |
  |------------------------->|                          |
  |  Login + consent UI      |                          |
  |<------------------------>|                          |
  |  302 → /callback?code=Z&state=...                   |
  |---------------------------------------------------->|
  |                          |  POST /oauth2/token       |
  |                          |  (code + verifier + secret)
  |                          |<-------------------------|
  |                          |  access + refresh + id_token
  |                          |------------------------->|
```

1. Your backend generates a PKCE verifier and CSRF state, then redirects the user's browser to `/oauth2/auth`.
2. The user logs in to Busha and consents on Busha's hosted screen.
3. Busha redirects the browser back to your callback URI with a one-time `code`.
4. Your backend exchanges the code (plus the PKCE verifier and your client secret) for tokens — server-to-server, never through the browser.

## Hosts and environments

| Environment | API host               | OAuth2 issuer            | Dashboard      |
| ----------- | ---------------------- | ------------------------ | -------------- |
| Production  | `api.busha.io`         | `login.busha.io`         | `app.busha.io` |
| Sandbox     | `api.sandbox.busha.so` | `login.sandbox.busha.so` | `app.busha.io` |

The two environments are fully isolated — credentials, users, and tokens do not cross between them. Always read the canonical issuer string from `/.well-known/openid-configuration` at startup rather than hardcoding it.

## Next steps

<CardGroup cols={2}>
  <Card title="Get access" icon="key" href="./get-access">
    Register your OAuth2 app and get your client credentials.
  </Card>

  <Card title="Quick start" icon="bolt" href="./quick-start">
    Make your first authorized API call end-to-end in minutes.
  </Card>

  <Card title="Scopes reference" icon="list" href="./scopes">
    Browse all 12 scopes and pick only what you need.
  </Card>

  <Card title="Token handling" icon="shield" href="./tokens">
    Learn how access tokens, refresh tokens, and rotation work.
  </Card>
</CardGroup>