Authentication(OAuth2.0), which is a mandatory step for an end-user to obtain a unique access/refresh tokens to access and control their own resources (e.g. Online AccountRight company file) via an application with an aid of MYOB api.
This article explains:
- How authentication works from a developer and an end-user point of view
- Troubleshooting authentication issues
- Authentication tips
How authentication works from a developer and an end-user point of view
There are 6 steps involved during authentication.
Step 1
You'll need to register your 'app' and receive an API Key and API Secret. You do this via the my.MYOB portal. Follow this article to get this key prepared: How do I register my application for an API Key?
Step 2
It starts out with your app presenting a button to a user asking them to connect to MYOB, which will direct the user to the MYOB secure login page. This button should contain a URL in below format:
https://secure.myob.com/oauth2/account/authorize?client_id={{api_key}}&redirect_uri={{redirect_url}}&response_type=code&scope=CompanyFile la.global
with the following URL Parameters:
| client_id | This is your API Key - you get that once you register an app in my.myob.com.au -> Developer tab |
| redirect_uri | The MYOB authentication server will need to redirect the user to your application. This URL is the place you expect to receive the authentication code. Note: The redirect URI must match the url you entered when registering for your API Key and must be URL DECODED. Watch for any trailing / as that catches lots of people out. Note: If you are building a desktop or mobile app and don't have a web service, then use http://desktop as the uri. |
| response_type | this should always be code as MYOB authentication services don't accept other response types |
| scope | The scope tells the MYOB authentication server what you are asking for. CompanyFile - This scope will give you access to all of the MYOB AccountRight files in a users account. la.global - This scope will give you access to all of the MYOB Essentials files in a users account. CompanyFile la.global - This scope will give you access to all of the MYOB AccountRight and Essentials files in a users account. The highly recommended option for new Essentials integration preparation. |
Step 3
The user will be presented with an MYOB secure login screen which looks like:
The user will sign in here and be presented with a screen informing them that your application is asking for permission to their MYOB files. This screen looks like:
Step 4
Once the user clicks the green Allow Access button they are redirected back to your app to the redirect uri you provided. In the URL there is a ?code= URL parameter that your application can now extract.
Note: because this code has been provided to your application via a URL, it will be urlencoded, you will need to decode it before you continue.
Step 5
Now that you have a decoded authentication code, you can now exchange that for OAuth access/refresh tokens. To do this you make a POST with the following URL and items, using a content type of application/x-www-form-urlencoded:
https://secure.myob.com/oauth2/v1/authorize| client_id | This is your API Key - you get that once you register an app in my.myob.com.au -> Developer tab |
| client_secret | This is your API Secret - you get that once you register an app in my.myob.com.au -> Developer tab |
| Scope | The scope tells the MYOB authentication server what you are asking for. CompanyFile - This scope will give you access to all of the MYOB AccountRight files in a users account. la.global - This scope will give you access to all of the MYOB Essentials files in a users account. CompanyFile la.global - This scope will give you access to all of the MYOB AccountRight and Essentials files in a users account. The highly recommended option for new Essentials integration preparation. |
| Code | This is the now decoded authentication code that was passed back to your application. |
| redirect_uri | This is your redirect uri - you get that once your register an app in my.myob.com.au -> Developer tab |
| grant_type | This is the type of grant you are requesting. It must say authorization_code because you are passing the MYOB server an authorization code. |
Here is an example of the Header and the body set up in Postman.
Header:
Body:
Step 6
Making this POST call will exchange the CODE, and the MYOB authorization server will return with a JSON payload. Within this payload you will find (among other things) an access_token and a refresh_token.
access_token -
A token required to establish the API connection with the online resource (e.g. AccountRight
company file). An access token lives for 20 minutes and a new access token needs to be obtained to
re-established the connection.
refresh token -
A token required to obtain a new set of access/refresh tokens. A refresh token lives for 1 week
period. Upon a new set of tokens request, it is recommended to update the stored access token but
also the refresh tokens too. You use the refresh token to ask for a new access token.
What if things don't quite go as planned?
If during your development and testing phase, things don't quite go as planned and you need to repeat a step. You will always need to restart at step 1. This is because authorization codes only work one time.
What if I get the dreaded invalid_request error? Don't dread, we've all been there, 99% of the time, it's a hiccup with the redirect_uri, check that.
Troubleshooting authentication issues
- Solving invalid request errors
- I'm getting the OAuthTokenIsInvalid error
- Revoking access
- Solving Access Denied errors
Authentication Tips
Comments
0 comments
Article is closed for comments.