OAuth 2.0 overview

OAuth 2.0 lets your application call the Bito API on behalf of a merchant account. The tokens Bito issues carry the tenant context, so every call is automatically scoped to that merchant's data — you never pass an account id yourself.

TIP

If you only ever serve one account — your own — you do not need OAuth. Send the api-key header instead; see Calling the API.

The two ways a code reaches you

There are two ways your application can obtain an authorization code. Both end at the same token endpoint, and both give you the same access_token + refresh_token pair.

You are building	Use	Who starts it
A marketplace integration merchants install from inside Bito	Install flow (Flow A)	The merchant, in the Bito admin panel
Your own product, where the merchant clicks "Connect Bito" in your UI	Connect flow (Flow B)	Your application
A background job with no user present, for a merchant that already installed you	Client credentials grant	Your server

                    Flow A                         Flow B
                (Bito-initiated)             (you-initiated)

  Merchant clicks Install in Bito     Merchant clicks Connect in your app
                |                                   |
                v                                   v
  Bito POSTs the code to your          You redirect to id.bito.uz, the
  redirect_uri                         merchant logs in, Bito redirects
                |                      back with ?code=
                |                                   |
                +-----------------+-----------------+
                                  |
                                  v
                     POST /auth/oauth/token
                     (grant_type=authorization_code)
                                  |
                                  v
                   access_token + refresh_token

Scopes

Scopes control how much access the merchant grants you.

Scope	Value	Description
Admin	admin	Full administrative access to all resources
Read	read	Read-only access
Write	write	Create and update resources
Delete	delete	Delete resources

Permissions: the real control

The scope on a token does not restrict a call by itself. Every Integration API request — with an OAuth token or with an api-key — is checked like this:

1. required_permissions → granted_permissions. Your app declares the ERP permissions it uses on the Integration API (required_permissions, the same keys roles are built from). The merchant sees exactly that list before installing, and installing writes a copy of it onto the integration as granted_permissions. Every call is checked against that copy; a call outside it is refused. If you change required_permissions later, an account that already installed you is affected only when it reinstalls. An empty list means all permissions.
2. available_scopes. If your client has available_scopes set, the scope matching the call's action (read, write or delete; admin covers all) must be on that list, or the call is refused. When the list is empty, this check is skipped.

Declare the narrowest required_permissions list that works — it is what the merchant reads to know what they are agreeing to before installing.

Endpoints

Method	Path	Auth	Purpose
POST	/auth/oauth/auth	None	Client credentials grant
POST	/auth/oauth/token	None	Exchange an authorization code, or refresh a token pair
POST	/auth/get-one-time-token	Bearer (user session)	Mint a one-time token

Host: https://api.bito.uz in production, https://api.systematicdev.uz on dev.