Articles in this section

Company file authentication

Avatar
Helen
  • Updated
Follow

Login and authentication is the very first step your clients will experience, and it is essential to make that as simple and straightforward as possible. In this guide, we'll explore how best to use the AccountRight Live API endpoints to build a seamless self-service login workflow for your clients.

This guide is written primarily for online files however you can use the same techniques to connect to desktop files as well.

Initial authentication

For company files stored online, the first step is to use OAuth2 to authenticate and gain access to the API on behalf of your client. If you haven’t already, now’s a great chance to check out the authentication guide to understand how OAuth2 works.

At the end of the Oauth2 login, your application will have received an access token and a refresh token that you’ve stored securely as part of your application. These tokens represent your application's access to the API on behalf of that user.

Listing company files

Using the access token, we can now make our first call to the AccountRight Live API to retrieve the list of company files we can access. This is called the API entry point or the company files endpoint. This API call will look similar to this:

GET /accountright/
Authorization: Bearer 
x-myobapi-key: xxxx
x-myobapi-version: v2
Accept: application/json

The response will be a JSON list of objects and the company files returned will vary depending on the access token that you've provided. If it is your first time building with the API you may only have one file (the sandbox file we’ve invited you to).

If you reach this point and you find your JSON list empty, it means that the access token you’ve used does not have access to any files. This can happen if your customer has logged via OAuth2 (so we know they have an MYOB account) in but they do not have an online file. You can read more about online files in this help guide.

There are three important fields to take note of from the company file endpoint.

  • Name: This is the name shown to clients in their library browser so it's likely they’ll recognise this as their company file.
  • URI: This is the URI that you can use to access the company file. For more information about this see our best practice guide for hypermedia.
  • ProductVersion: This is the AccountRight Live version (e.g. 2018.1). You can use this to determine which API features and endpoints are available.

/Info endpoint

When you connect to the AccountRight Live API, it can be useful to query the /Info endpoint to retrieve information about the resources, URIs and versions that are available. This can change over time as customers upgrade their AccountRight Live client, and as we release new product versions to the cloud.

You can see, for example, the /Contact/Customer endpoint was added in 2013.3 release and can be seen in the API response as:

...
{
    "ResourcePath": "/Contact/Customer/",
    "Version": "v2",
    "FromProductVersion": "2013.3",
    "ToProductVersion": null,
    "MinimumProductLevel": {
        "Code": 10,
        "Name": "Basic"
    }
}
...

You can use a company file's ProductVersion and the /Info endpoint to proactively determine your application's compatibility with AccountRight Live API features. For example, features added in 2018.1 will not be available in files with 2017.2 ProductVersion.

Tip: AccountRight Live uses a YEAR.release versioning convention. This means you can generally use string comparison to determine your support. e.g. "2018.1" > "2017.2" means that 2018.1 was released after 2017.2.

At this point we've established:

  • Company File version
  • API resources & endpoints
  • The product version that your application currently supports.

Logging into a file

Now that we have the Company File URI lets go ahead and see what permissions we have within the company file.

To do this, we're going to call the /CurrentUser endpoint within your file of choice using the Company File URI we retrieved above.

GET {company file URI}/currentuser
Authorisation: Bearer 
x-myobapi-key: xxxx
x-myobapi-version: v2
Accept: application/json
If you get a successful HTTP 200 response, the JSON will include a list of all resources that you have permission to access. You may have administrator access or a restricted user access as defined by the roles within a company file.
 
If you get an HTTP 403 "Access Denied" response, you don't yet have permissions to login to that file. This is because some users have not linked their my.myob login with their per-file company file login. You could prompt them to link their login (it's Step 5 of our help guide "Opening a company file"), or you could allow your client to provide their per-file user credentials to your application.
 
Should you choose to prompt your client for credentials, these become the x-myobapi-cftoken header (see our Headers documentation). Make sure you store these securely per-user as there are multiple users per-file.
 
Reattempting to call the /CurrentUser endpoint with your cftoken should result in an HTTP 200 success response (or your client might have mistyped their credentials - so double check that too).
 

Recovering from errors

Over time, its possible for your access to a file may change and its important that you can handle these changes. You can use the error messages from the API to step backwards through authentication to recover and reconnect.,
 
First, "Access denied" errors will hint that the user credentials or roles have changed. This is a chance to recheck the /CurrentUser endpoint and prompt your client to login to the file again.
 
Secondly, an InvalidOauthToken error means its time to refresh your OAuth2 tokens by using the refresh endpoint.
 
If you continue to get InvalidOauthToken errors, it might mean that your access has been revoked. You can prompt your client to log in again using OAuth2.
 
By implementing the steps outlined above, your connected solution can be entirely self-service with onboarding of a new AccountRight Live client as a seamless experience for your client. This allows you to connect to more customers with less effort.

Related articles

Comments

0 comments

Article is closed for comments.