Skip to main content

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.

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

​
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

Portfolio dashboard

Read balances and transaction history across a user’s Busha wallets. Use balances:read and transactions:read.

Deposit flow

Read existing deposit addresses or generate new ones on the user’s behalf. Add addresses:read and addresses:write.

Outbound transfers

Initiate transfers to saved or new recipients. Add recipients:read, recipients:write, transfers:read, and transfers:write.

FX / trading widget

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.

​
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

EnvironmentAPI hostOAuth2 issuerDashboard
Productionapi.busha.iologin.busha.ioapp.busha.io
Sandboxapi.sandbox.busha.sologin.sandbox.busha.soapp.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

Get access

Register your OAuth2 app and get your client credentials.

Quick start

Make your first authorized API call end-to-end in minutes.

Scopes reference

Browse all 12 scopes and pick only what you need.

Token handling

Learn how access tokens, refresh tokens, and rotation work.