Oauth2 MoonBack

You can choose to restrict MoonBack access based on a specific user access, thus linking your Token with a specific user and a specific company.

To do so, we use OAuth 2.0, an industry-standard protocol. It allows our application to access specific user data without requiring a private user's credentials. A good representation of the protocol can be found here

Register your application

👍

Register your app with MoonBack

In order to connect to MoonBack via OAuth 2.0, your app must be registered. To ask to be registered, just contact support. We will validate your demand and assign you a specific Client Id and Client Secret. The Client Secret should not be shared.

Once registered, you app will be able to ask for specific permission scopes and will be rewarded with an access token upon a user's approval. An access token is linked to a specific user and to a specific company.

Step 1 : "Sign in with MoonBack" button

Once you get your client id and client secret, you can include in your app a "Sign in with MoonBack" button. This button should redirect users to the following URL : https://app.moonback.me/oauth/authorize. The following parameters should be passed as GET parameters:

Parameter	Required	Description
client_id	yes	Id provided by MoonBack once your app is registered
redirect_uri	yes	URL to redirect to after user approval (whether successful or not)
response_type	yes	Type of authentication flow. Must be code.
state	no	A security parameter. A unique string that sent back to you at the end of the authentication process.

Once loaded, the page will ask the logged user to pick one of his accessible companies.

Step 2 : Users are redirected with an authorization code

After getting the user's approval to authorize your app, MoonBack will redirect the user to the redirect_uri you provided with an authorization code GET parameter and the state parameter if you provided one in the previous state. You should compare the received state with the one you provided. If they don't match, the request may have been compromised, you should abort the process.

Step 3 : Exchange Authorization Code <=> Bearer Token

Once you compared the state, you can exchange the authorization code provided in step 1 with an actual bearer token. To do so, you should make a post request on https://app.moonback.me/oauth/token. The following parameters should be passed as body parameters:

Parameter	Required	Description
client_id	yes	Id provided by MoonBack once your app is registered
client_secret	yes	Client Secret provided by MoonBack once your app is registered
code	yes	The code received in step 2.
redirect_uri	yes	URL to redirect to once our server handled your request (whether successful or not)
grant_type	yes	Must be authorization_code at this step. Only authorization_code and refresh_token are currently supported

If the client_id / client_secret / code are all valid, MoonBack will send you a JSON response containing an access_token, an expiration date and a refresh_token. You must store the access_token and the refresh_token.

JSON

{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "token_type": "Bearer", 
 "expires_in": 86400,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}

Refresh the token

Once the access_token has reached its expiration date, you won’t be able to access MoonBack anymore. You'll need to request a new one through a post request at https://app.moonback.me/oauth/token.
The following parameters should be passed as body parameters:

Parameter	Required	Description
client_id	yes	This id will be provided by MoonBack once you ask us to registrer your application
client_secret	yes	Client Secret will be provided by MoonBack once you ask us to registrer your application
refresh_token	yes	The refresh token provided by MoonBack once you create the access_token
grant_type	yes	Must be refresh_token at this step. Only authorization_code and refresh_token are supported