API Reference
Log In

Authentication Flow

All API interactions require you to have authentication credentials. Use the client_id and client_secret obtained while creating an app to authenticate yourself against the API. We provide an access_token/refresh_token Oauth2 authentication.

The application can ask the following 10 scopes explicitly:

  • store-inventory:read
  • store-orders:read
  • store-settings:read
  • store-inventory:write
  • store-orders:write
  • store-settings:write
  • user-contact:read
  • user-info:read
  • payments:read
  • payouts:read

Steps to generate an access token for the app user

The oauth2 flow will work as described below

We have taken some example values for all the data points like Client ID, Client Secret, Redirect URI and State. Please use the actual values.

  • From the Frontend Make GET request on /oauth2/authorize

Examples :

Sample Request 1 (one scope - payments:read):

https://www.instamojo.com/oauth2/authorize?scope=payments:read &redirect_uri=https://app.example.com/oauth2/callback 
&response_type=code&client_id=812741506391&state=af0ifjsldkj

Sample Request 2
(multiple scopes - all (space delimited)):

https://www.instamojo.com/oauth2/authorize?scope=payments:read payouts:read orders:read user-info:read user-contact:read &redirect_uri=https://app.example.com/oauth2/callback 
&response_type=code&client_id=812741506391&state=af0ifjsldkj
  • Above we have shown a couple of sample GET requests, with one and multiple scopes (In case of multiple scopes, scopes need to be separated by a space)
  • The redirect_uri is the URL of the client application that the authorization grant should be returned to.
  • The value of redirect_uri should match the value from the App registration process (at Instamojo). We need to make sure that the authorization is not being bounced back to a foreign application.
  • Client ID can be accessed as shown in 7th step of the Setup process (Page 6)
  • State is a security flag, similar to CSRF
  1. If the above request is valid then the user is redirected to an authorize page, shown below
1016

If the user authorizes the app, the user is redirected to the application.
Response:

HTTP/1.1 302 Found
Location: https://app.example.com/oauth2/callback?
code=MsCeLvIaQm6bTrgtp7&state=af0ifjsldkj

The code returned is the authorization grant and state is to ensure it's not forged and it's from the same request. The authorization code is valid for 60 seconds.

1134
  • After the Frontend process is done, a Backend flow needs to be triggered, exchanging the authorization code for an access token. The Developers (clients) application sends an access token request to the token endpoint on the Authorization Server with the client id and client secret. This process exchanges an Authorization Code for an Access Token and (optionally) a Refresh Token. The client can now access a protected resource with an Access Token.

Below is how this looks in raw HTTP (example).

Request:

POST /oauth2/token/ HTTP/1.1
Host: www.instamojo.com
Content-Type: application/x-www-form-urlencoded
code=MsCeLvIaQm6bTrgtp7&client_id=812741506391&client_secret={client_secret} &redirect_uri=https://app.example.com/oauth2/callback&grant_type=authorization_code

The grant_type is the extensibility part of OAuth. It's an authorization code from a precomputed perspective. 

Response:

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 36000,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Access Token is valid for 36000 sec i.e. 10 hours. The application needs to store access token and refresh token, also expire time for an access token which is creation time + 36000 sec.

  • Once the application has an access token, applications need to use the access token in an Authentication header (using the token_type as a prefix) to make protected resource requests.
curl -H "Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA" \
  https://api.instamojo.com/v2/user-info/

Note: Access token will get expired after 10 hours from the date of creation. The application should track for the expired access token and generate new access token by exchanging refresh token

To exchange the Refresh Token you received during authorization for a new Access Token, make a POST request to the /OAuth/token endpoint in the Authentication API, using grant_type=refresh_token.

curl --request POST \
  --url 'https://www.instamojo.com/oauth2/token/' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data refresh_token=YOUR_REFRESH_TOKEN

Skip authorization form

Depending on the OAuth2 flow in use and the access token policy, users might be prompted for the same authorization multiple times, sometimes this is acceptable or even desirable but in some use cases, it isn’t. To control that behavior you can use the approval_prompt parameter when hitting the authorization (/authorize) endpoint. Possible values are:

  • force - users are always prompted for authorization.
  • auto - users are prompted only for the first time, subsequent authorizations for the same application and scopes will be automatically accepted.

Access token or Refresh token revocation

To revoke the access token or refresh token for the application user, please use the below post request:

POST /o/revoke_token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
token=XXXX&client_id=XXXX&client_secret=XXXX