Authentication

What is OAuth2

OAuth is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords. POSRocket uses only the Authorization code grant type to authenticate the 3rd party apps into the businesses data.

How to get an access token

you can follow the below steps to grant an access token which you can use to receive the data from the API endpoints:

  1. Login into your launchpad account and go to your app settings page.

  2. On the redirect URI field add http://localhost:8080/callback where /callback page is the page that will handle retrieving the access_token will describe it in detail below.

  3. On your web application you need to redirect the user to this URL:
    https://developer.posrocket.com/oauth/authorize/?redirect_uri=<yout redirect uri>&response_type=code&client_id=<yout client id>&access_type=offline.  
    Please note that the redurect_url query param should match the redirect URI setting that you set in your app.

  4. Launchpad will display a login screen for the user to enter his POSRocket credentials and make sure that his data is verified.

  5. Launchpad will display a confirmation screen for the scopes that your app wants to have access to.

  6. If all is good launchpad will redirect the user back to your return URL with the code query param to retrieve access token: 
    http://localhost:8080/callback?code=<grant code>

  7. Once you receive the code you will need to send server to server POST request to this URL: 
    https://developer.posrocket.com/oauth/token/ 
    with the following body: 
    code=<grant code>&redirect_uri= http://localhost:8080/callback&client_id=<your app id>&client_secret=<your app secret>&grant_type=authorization_code

  8. You will receive the following JSON response back from sending that post request: 

    {
      "access_token": "AYjcyMzY3ZDhiNmJkNTY",
      "refresh_token": "RjY2NjM5NzA2OWJjuE7c",
      "token_type": "bearer",
      "expires": 3600
    }
  9. Now you can attach the access token to the header when sending API requests to authenticate the request by adding an Authorization header to your request and the value should be something like this Bearer <your access token>.

How to get a refresh token

When you initially received the access token, it may have included a refresh token as well as an expiration time like in the example below.

The presence of the refresh token means that the access token will expire and you’ll be able to get a new one without the user’s interaction.

The “expires” value is the number of seconds that the access token will be valid. It’s up to the service you’re using to decide how long access tokens will be valid and may depend on the application or the organization’s own policies. You can use this to preemptively refresh your access tokens instead of waiting for a request with an expired token to fail.

If you make an API request and the token has expired already, you’ll get back a response indicating as such. You can check for this specific error message, and then refresh the token and try the request again.

If you’re using a JSON-based API, then it will likely return a JSON error response with the invalid_token error. In any case, the WWW-Authenticate the header will also have the invalid_token error.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
  error_description="The access token expired"
Content-type: application/json
 
{
  "error": "invalid_token",
  "error_description": "The access token expired"
}

When your code recognizes this specific error, it can then make a request to the token endpoint using the refresh token it previously received and will get back a new access token it can use to retry the original request.

To use the refresh token, make a POST request to the service’s token endpoint with grant_type=refresh_token, and include the refresh token as well as the client credentials.

POST /oauth/token/ HTTP/1.1
Host: authorization-server.com
 
grant_type=refresh_token
&amp;refresh_token=xxxxxxxxxxx
&amp;client_id=xxxxxxxxxx
&amp;client_secret=xxxxxxxxxx

The response will be a new access token, and optionally a new refresh token, just like you received when exchanging the authorization code for an access token.

{
  "access_token": "BWjcyMzY3ZDhiNmJkNTY",
  "refresh_token": "Srq2NjM5NzA2OWJjuE7c",
  "token_type": "bearer",
  "expires": 3600
}

If you do not get back a new refresh token, then it means your existing refresh token will continue to work when the new access token expires.

Keep in mind that at any point the user can revoke an application, so your application needs to be able to handle the case when refreshing the access token also fails. At that point, you will need to prompt the user for authorization again.