Changes to the WorkflowMax API
By now you’ve probably heard that we’re taking steps to secure our ecosystem because of a new framework for digital services providers from the Australian Tax Office and similar standards from tax offices throughout the world. There are changes to all of our APIs but there are some especially large changes that are specific to consumers of the WorkflowMax/Xero Practice Manager API that we’d like to talk about here.
The ABSIA standard for Add-on Marketplaces requires us to assess the security of all developers that have access to a list of clients in an accounting or bookkeeping practice. Those requirements include filling out a questionnaire about security practices once a year. For more details on this you can watch our video about security self assessments or read our documentation here.
So what is changing for WorkflowMax and Xero Practice Manager?
1. The current v1 WorkflowMax API will be deprecated
The WorkflowMax API has served us well but it’s time for an upgrade. In order to comply with legislation, we need to make multiple breaking changes that will change the way you interact with our API. Making a clear distinction between the old v1 API and the new v3 APIs enables us to keep your current connections alive while you switch over to the new API. We plan to turn off the v1 WorklfowMax API in December 2020 and Xero Practice Manager accounts will no longer be accessible after the 30th of September 2020.
2. We’ve separated the WorkflowMax and Xero Practice Manager APIs
Until now access to Xero Practice Manager accounts was through the WorkflowMax API because the two applications share a lot of the same underlying systems. In the future, we want to be able to provide different features and services between the two systems. The deprecation of the v1 API has given us a great opportunity to separate things. We think this is less confusing for API consumers and their customers too. You won’t be able to access Xero Practice Manager Accounts from the WorkflowMax API, or access WorkflowMax accounts from the Xero Practice Manager API.
3. We’re changing how you authenticate
There were a few different ways to authenticate with the v1 API. This involved either contacting our support team for a key, or using a unique authentication method that didn’t abide by any particular authentication standard. To make this easier, and more secure, for you and your customers, we’ve chosen to secure the v3 APIs using the same OAuth 2.0 flow that we use for the Xero Business API. There are more details on our OAuth 2.0 implementation available here.
4. The URL you use to access the API will be different
It will be https://api.workflowmax.com/v3/ for WorkflowMax and https://api.xero.com/practicemanager/3.0/ for Xero Practice Manager.
5. WorkflowMax is transitioning to use GUIDs instead of IDs
Any entity (like a client, job, etc) that is currently identified using a numeric ID (e.g 1235) will transition to being identified by a Globally Unique IDentifier (GUID) instead (e.g. 4d43f1c8–25e4–4aac-a5d6-a8d998c67210). There are many advantages to using GUIDs and we’ll try to cover off our experience with them in a future blog post. For now, just know that you’ll need to support them by the 30th of November 2020. An in-depth guide on how to transition from IDs to GUIDs can be found here. Xero Practice Manager will undergo a similar transition in the future but no dates have been set for that change yet.
6. In order to use the v3 Xero Practice Manager API you’ll need to be granted access
Newly legislated security requirements require we control who has access to data in accounting and bookkeeping practices. If you need access to the Xero Practice Manager API, and you haven’t already received an email from us, you can request access here.
7. Rate limits for the v3 APIs are different from those on the v1 API
We’ve made rate limits for the v3 APIs the same as the Xero Business APIs. In general this means a limit of 60 calls a minute and 5000 calls a day. You can find more details here.
That’s a lot of information and you’ve probably got questions, so we’ve tried to anticipate some of them below.
Why are you jumping from v1 to v3? What happened to v2?
Version 2 of the API actually exists, but it is a private internal API for WorkflowMax.
Do you have any SDKs available for use with the new APIs?
We have a WorkflowMax code sample for .Net Core and another .Net Core code sample for Xero Practice Manager. You might want to take a look at the Xero API SDKs to see how they are using OAuth 2.0 or you can check out our Postman example for WorkflowMax here.
I’m trying to authenticate to my WorkflowMax/XPM account but it says I don’t have an account. What can I do?
Go to your staff list in WorkflowMax and click on your user name. Scroll to the very bottom of the page and tick “Authorise 3rd Party Full Access”
If you’re trying to connect to a Practice Manager account using the WorkflowMax API then you won’t be able to see an account either.
I’m using the Xero Practice Manager API. When do I need to complete the security assessment by?
June 30th 2020.
Do I need to complete a security assessment if I’m using the WorkflowMax API?
Only if you’re connected to 1000 or more WorkflowMax accounts
