Authentication

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.

Online & oauth

Authentication in the Online 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 Business 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.

Note: The returned Code expires in 2-5 minutes since its generation.

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.
The response will look like:

{
    "access_token": "AA_[TRUNCATED_FOR_READABILITY]_aA1",
    "token_type": "bearer",
    "expires_in": "1200",
    "refresh_token": "_hO1!I_[TRUNCATED_FOR_READABILITY]_FEg",
    "scope": "CompanyFile",
    "user": {
        "uid": "28_[TRUNCATED_FOR_READABILITY]_5c",
        "username": "user@emailaddress.com"
    }
}

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.

The refresh token response will look like:

{
    "access_token": "AAE_[TRUNCATED_FOR_READABILITY]_JT",
    "token_type": "bearer",
    "expires_in": "1200",
    "refresh_token": "_hO1!I_[TRUNCATED_FOR_READABILITY]_KQ",
    "scope": "CompanyFile"
}

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.

Validating the User

Now you can vaildate the user that you have authicated with. For more details on how to do this, head over to our Knowledgebase aricle for Validating the Users.

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

Extra Reading

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