Bitnob for Business OAuth 2.0

Bitnob's Oauth2.0 flow

Bitnob for Business Oauth 2.0 setup allows you to access Bitnob user details. It enables your app to make requests on behalf of a user without getting direct access to their credentials. An app integrated with Bitnob requests for specific permission scopes and gets access and refresh tokens after the user's approval.

Registering an App to access Bitnob's Oauth2.0

An App has to be registered on the Bitnob app to gain OAuth access and given a unique Client ID and Client Secret.

❗️

Client Secret Security

Client secrets should be secured.

Oauth 2.0 Flow

Step 1 - Sending users to authorize

Your web or mobile app should redirect users to the following URL:
https://oauth.bitnob.co/login (production)
https://sandbox-oauth.bitnob.co/login (sandbox)

The following values should be passed as parameters in a GET request:

All parameters are required.

The scope parameter is a space-separated list of scopes, to indicate several aspects of a Bitnob user authorization you would like to have access to. The list for the scope is below.

The state parameter is used to avoid CSRF attacks by passing in a value that's unique to the user you're authenticating and checking it when authentication is done.

📘

Redirect URL

Redirect URLs and URIs may not contain an anchor (#).

Users have to be existing bitnob users to authorize or would be redirected to App stores to sign up to continue authorization access; regardless of provided scope parameter.

Step 2 - Users are redirected to your server with a verification code

After a user has authorized your app, We will redirect the user to your set redirectUrl as a GET request with the state parameter you provided and an authorization code.

🚧

Verification Code

Verification codes are only shared once and expire after 10 minutes.

Step 3 - Exchanging a verification code for an access token

If all is well, exchange the authorization code for an access token using the OAuth. access API method.

https://api.bitnob.com/api/v1/oauth/access

All parameters are required.

You'll receive a JSON response containing an accessToken parameter (among other details):

{
    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJJc3N1ZXIiOiJJc3..",
    "scope": "read",
    "tokenType": "bearer"
}

Access tokens for all apps are also known as bearer tokens. You can then use this token to call API methods on behalf of the user. The token will continue functioning until the installing user either revokes the token.
NB: Please note that the user access tokens do not expire.

👍

Securing tokens in your DB

Please note that the user access tokens do not expire. To ensure the reuse of tokens and avoid a repeated OAuth process, it is advisable to save tokens in your DB

Step 4 - Denied Requests

After a user denies your request, Bitnob will send a GET request to the redirectUrl with the error parameter and the state parameter you provided

http://your_redirectUrl.com/oauth?error=access_denied&state=xxxxxxxx

Using access tokens

The tokens awarded to your app can be used in requests to the Web API.
The best way to communicate your access tokens, also known as bearer tokens, is by presenting them in a request's Authorization HTTP header:

*GET /api/v1/app/user-profile?scope=user:ln_address*
Authorization: Bearer eyJhbGciO.1234.abcdefgh

Defined Scopes

Wallet

User profile

Authorizations and Appending Scopes

When you initially send a user through the OAuth flow, you receive a token that has the set of scopes you requested. Any subsequent time(s) you send that same user through the OAuth flow, any new scopes you request will be added to that initial set.

For example, if you initially request user_profile:ln_address and wallet:transactions from a user, the initial token will only be scoped to user_profile:ln_address wallet:transactions.
If you send that same user through a second OAuth flow, this time requesting wallet:balance, the resulting token will have the new scope added to the previous set: user_profile:ln_address wallet:transactions wallet:balance.
This process can be repeated any number of times, and each scope you request is additive to the scopes you've already been awarded.

Every API request returns an X-OAuth-Scopes HTTP header with the response. This indicates all scopes of the current token. An example: X-OAuth-Scopes: user:ln_address`

📘

Downgrading Scopes

It is not possible to downgrade an access token's scopes.

Revoking tokens

To revoke an OAuth Token use /api/v1/oauth/revoke.

Revoking tokens and asking a user to authenticate again is the best way to start over and incrementally add more limited OAuth scopes to a token.