Authentication

  Date Updated: Sep 4th 2013

The AccountRight Live API can be used with both desktop and online company files, however the authentication for both is slightly different.

Working locally?

Authentication in the desktop environment

For desktop files, the authentication process is straightforward, once the user selects a company file to work with, your app asks them to login using a username and password for that particular company file. No further authentication is required.

For any call you make to the API you pass the following header to supply the company file credentials of username and password which have been BASE 64 encoded.


'x-myobapi-cftoken: [Base64Encode(username:password)]'

The x-myobapi-cftoken expects you to pass it the username and password in a Base 64 Encoded string. Note the username and password must be separated with a : before encoding - more details here.

Cloud & oauth

Authentication in the cloud environment

When you're working with online files, your app will first need to access the user's my.MYOB account before it can access their company files. The MYOB API uses OAuth 2.0 to ensure that access to company files is handled securely.

Getting an Access Code

The first step for this is getting an access code & you do this by having your app user login to their my.MYOB account. Of course because it's OAUTH your app is not allowed to ask for a users my.MYOB credentials, instead you redirect them to our secure.myob.com login page here:


https://secure.myob.com/oauth2/account/authorize?client_id=[YOUR API KEY]&redirect_uri=[URL_ENCODED_REDIRECT_URI]&response_type=code&scope=CompanyFile

Note: The redirect URI must match the url you entered when registering for your API Key and must be URL ENCODED.

Once the User has authorised your app to access their company files they will be returned to your REDIRECT URL with a ?code= in the URL. You use this code for the next step

State - roundtrip parameter

A number of developers have asked if we support the state parameter. The answer is YES we do.

If you wish to pass an additional identification variable that you want our oauth server to return to you along with the access code, then simply add &state=[custom_var] to the url.

Read our blog post on passing the state parameter

Getting an Access Token

Once you have the access code, you make another call to our secure.myob.com server to request an access token. (note: we'll return both an Access Token and a Refresh Token).

You do this by POSTing the following parameters:


'client_id' // your API Key
'client_secret' // your API Secret
'scope' // this should say CompanyFile
'code' // the Access Code you just got
'redirect_uri' // your redirect URL
'grant_type' // this should say authorization_code

To this url:


https://secure.myob.com/oauth2/v1/authorize


You may also need to provide an appropriate Content-Type header.

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

This will return an Access token to you which you can use when making a call.

Example Call

Here's an example, note that the code and redirect_uri are both url_encoded.


code=Wvof%21IAA[[TRUNCATED_FOR_READABILITY]]luF&redirect_uri=http%3A%2F%2Flocalhost%2Fmyob_redirect%2F&client_id=[[MY_API_KEY]]&scope=CompanyFile&client_secret=[[MY_SECRET]]&grant_type=authorization_code

Note: while the data is formatted into a URL Query String you do not pass the information via the URL (that would be a GET request), you must pass the query string in the body and POST this to https://secure.myob.com/oauth2/v1/authorize

If the URL you are trying to POST to looks like:


https://secure.myob.com/oauth2/v1/authorize?code=Wvof%21IAA[[TRUNCATED_FOR_READABILITY]]luF&redirect_uri=http%3A%2F%2Flocalhost%2Fmyob_redirect%2F&client_id=[[MY_API_KEY]]&scope=CompanyFile&client_secret=[[MY_SECRET]]&grant_type=authorization_code
you are trying to GET and this will fail.

Refreshing an Access Token

Access tokens have a limited life span and when you receive one you'll also receive an Expiry Time for it and a Refresh Token. Once your access token expires it can no longer be used to access the API. So you'll need to trigger a refresh. You do this by POSTing the following parameters:


'client_id' // your API Key
'client_secret' // your API Secret
'refresh_token' // your refresh token
'grant_type' // this should say refresh_token

To this url:


https://secure.myob.com/oauth2/v1/authorize

Note: while the data is formatted into a URL Query String you do not pass the information via the URL (that would be a GET request), you must pass the query string in the body and POST this to https://secure.myob.com/oauth2/v1/authorize

If the URL you are trying to POST to looks like:


https://secure.myob.com/oauth2/v1/authorize?code=Wvof%21IAA[[TRUNCATED_FOR_READABILITY]]luF&redirect_uri=http%3A%2F%2Flocalhost%2Fmyob_redirect%2F&client_id=[[MY_API_KEY]]&scope=CompanyFile&client_secret=[[MY_SECRET]]&grant_type=authorization_code
you are trying to GET and this will fail.

Making a call

Once you have your tokens you can make any call to the API by simply passing the following headers along with any call to the API


'Authorization: Bearer [ACCESS TOKEN]'
'x-myobapi-cftoken: [Base64Encode(username:password)]'
'x-myobapi-key: [API KEY]' 
'x-myobapi-version: v2'

For more details on the headers used for our API go to our Headers documentation page.

Note:

Even though OAuth authentication takes care of logging in to the user’s my.MYOB account, the user will still need to enter a company file user ID and password before they can access individual company files linked to their my.MYOB account.

You'll notice above the x-myobapi-cftoken requires a base 64 encoding of the company file username and password - exactly the same as if you were doing it on the desktop.

Helpers

Code samples to help you

We've prepared some code to help get you up and running:

Extra Reading

For more information about OAuth authentication, see the OAuth website.