#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.
Downgrading Scopes 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 (opens in a new tab) (production)
https://sandbox-oauth.bitnob.co/login (opens in a new tab) (sandbox)
The following values should be passed as parameters in a GET request:
Parameters | Description |
---|---|
clientId | issued when you created your app |
scope | permissions to request |
redirectUrl | URL to redirect users back to |
state | unique string to be passed back upon completion |
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 (opens in a new tab)
params | description |
---|---|
clientId | issued when you created your app |
clientSecret | issued when you created your app |
code | a temporary authorization code |
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
Scope | What it gives you access |
---|---|
wallet:balance | User Balance |
wallet:transactions | User Transactions |
User profile
Scope | What it gives you access |
---|---|
user:username | User Username |
user:email | User Email Address |
user:ln_address | User Bitnob Lightning Address |
user:custom_ln_address | User Custom Lightning Address |
user:verification_level | User KYC Verification Level |
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.