How to Authenticate

How it works

SMEasy uses the OAuth 2.0 protocol for authentication and authorization. OAuth2 is a framework that enables applications to obtain limited access to user accounts over HTTP. It is used by services like Google, Facebook, Stripe, and Slack. This method creates a token that lasts for 12 hours to keep your SMEasy account secure and connected. For more details about OAuth2 itself, check out: the official documentation.

Work Flow Overview

1. Your user needs to allow your application to access their SMEasy account info via the SMEasy API. As part of this process you will get an auth code back from SMEasy.
2. You will need to exchange this auth code for an access token and refresh token pair.
3. When the users access token expires you can use the associated refresh token to request a new access token and refresh token pair.
4. Rinse and repeat step 3.

Step 1: Get an auth code

In order to get your user to allow your application to access their SMEasy accounting data from SMEasy you will need to send your user to a page hosted by SMEasy which will prompt your user to:

1. Provide a page on your site asking your user to 'connect' their SMEasy account to your application. Your user should be able to click on a button or a link that will take them through to step 2.
2. The link on your website should take your user to an SMEasy hosted page where they will be prompted to do the following:
   • Login to their SMEasy account to prove who they are to SMEasy.
   • Allow your application to access their SMEasy accounting data via the SMEasy API.
   • Redirect back to your application with attached auth code and state.

Where do you redirect your user when they click on the relevant button or link in step 1?

Where:

• <CLIENT_ID> is the value you got back from SMEasy support when listing your application with SMEasy.
• <REDIRECT_URI> is the value you supplied to SMEasy support when listing your application with SMEasy.
• <STATE> is a unique text value that is used to validate that the response you get at your redirect_uri originated from your call to the SMEasy authorize link made in step 1 above.

Step 2: Exchange your auth code for an access token / refresh token pair

Once your user has authorised your application to access their SMEasy accounting data and you have received the resulting auth code you can proceed to the next step which is exchanging this auth code for an access token and refresh token pair.

To do this you will need to perform a POST against the following url:

With the following request header:

• Content-Type: application/x-www-form-urlencoded

With the following body:

grant_type=authorization_code&code=<AUTH_CODE>&redirect_uri=<REDIRECT_URI>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Where:

• <AUTH_CODE> is the auth code retrieved from step 1 of this process.
• <CLIENT_ID> and <CLIENT_SECRET> are the values you got back from SMEasy support when listing your application with SMEasy.
• <REDIRECT_URI> is the value you supplied to SMEasy support when listing your application with SMEasy.

You should received back from the above POST the following json:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 297,
  "scope": "read offline_access",
  "refresh_token": "eyJhbGci..."
}

You will need to store the refresh token as you will need it in the future when the access token expires in 12 hours.

Step 3: Exchange your refresh token for a new access token / refresh token pair.

When the access token you are using to access the SMEasy API expires you will need to request a new access token and refresh token pair using the refresh token associated with the recently expired access token.

To do this you will need to perform a POST against the following url:

With the following request header:

• Content-Type: application/x-www-form-urlencoded

With the following body:

grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&redirect_uri=<REDIRECT_URI>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Where:

• <REFRESH_TOKEN> is the last refresh token retrieved from the SMEasy token endpoint.
• <CLIENT_ID> and <CLIENT_SECRET> are the values you got back from SMEasy support when listing your application with SMEasy.
• <REDIRECT_URI> is the value you supplied to SMEasy support when listing your application with SMEasy.

You should receive back from the above POST the following json:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 297,
  "scope": "read offline_access",
  "refresh_token": "eyJhbGci..."
}

Once again you will need to store the refresh token for future use.

About Refresh Tokens

access tokens are not long lived. They last for 12 hours, after which they are no longer able to authenticate requests, and may produce different errors depending upon the service being called. The remedy to use in these situations is a refresh token.

refresh tokens live forever, but are one-time-use, and only one refresh token can be alive at any time per user per application. A new refresh token is generated every time an access token is issued for a given user of a given application, and all old refresh tokens immediately become invalid. Make sure that whenever you receive a new access token, you write its companion refresh token down somewhere safe to refresh your access, or you’ll have to re-authorize your application again manually.

access tokens don’t interfere with each other’s lives the same way, so you could have several valid access tokens at any given point in time. They only expire when you manually POST to the token/revoke endpoint or when their time runs out.