Before you get started
Before you can start using OAuth with , you will need to have:
- a developer/user account
- a developer application – this can be created here
- an account to integrate with your developer application.*
*You must have full access to the “Authorize 3rd Party Full Access” privilege to integrate with a account.
How it works
supports the OAuth 2.0 Authorization Code grant type, which can be broken down into five basic steps:
- Your application opens a browser window to send the user to the OAuth 2.0 server.
- The user reviews the requested permissions and grants the application access.
- The user is redirected back to the application with an authorization code in the query string.
- The application sends a request to the OAuth 2.0 server to exchange the authorization code for an access token.
- Make calls against the API.
Getting OAuth 2.0 tokens
Step 1: Create the authorization URL and direct the user to 's OAuth 2.0 server
When sending a user to 's OAuth 2.0 server, the first step is creating the authorization URL. This will identify your application and define the resources (scopes) it's requesting access to on behalf of the user.
Your application should direct users to the following URL:
https://oauth.workflowmax2.com/oauth/authorize?response_type=code&client_id={YOURCLIENTID}&redirect_uri={YOURREDIRECTURI}&scope= openid profile email workflowmax offline_access&state={YOURSTATE}&prompt=consent
The following values should be passed in as parameters:
| response_type | code |
| client_id | Issued when you created your developer application |
| scope | Permissions to define the data that this application will access openid email profile workflowmax offline_access |
| redirect_uri | The URL on the server to redirect back to (this must be HTTPS) |
| state | random string you can generate to prevent XSRF |
| prompt | consent |
Optional parameter - does not have to be included but it is recommended for security purposes
Step 2: Prompts user for consent
displays a consent window to the user showing the name of your application and a short description of the API services it's requesting permission to access. The user can then grant access to your app.
If any errors occur or the user denies the request, we redirect back to your redirect_uri with an error parameter.
Your application doesn't do anything at this stage. Once access is granted, the OAuth 2.0 server will send a request to the callback URI defined in the authorization URL.
Step 3: Handle the OAuth 2.0 server response
When the user has completed the consent prompt from Step 2, the OAuth 2.0 server sends a GET request to the redirect URI specified in your authentication URL. If there are no issues and the user approves the access request, the request to the redirect URI will be returned with a code query parameter attached.
If the user doesn't grant access, the request to the redirect URI will be returned with a query parameter:
| error | access_denied |
| error_description | The resource owner or authorization server denied the request |
Step 4: Exchange authorization code for tokens
After your application receives an authorization code from the OAuth 2.0 server, it can exchange that code for an access and refresh token.
To do this you will need to make a POST request to our token endpoint:
https://oauth.workflowmax2.com/oauth/token
The request body will need to contain the following:
|
grant_type |
authorization_code |
| code | The authorization code you received in the callback |
| redirect_uri | The same redirect URI that was used when requesting the code |
| client_id | The app Client ID |
| client_secret | The app’s Client Secret |
Please note this is different to the WorkflowMax by Xero API, which passes this information via headers.
The token endpoint will verify all the parameters in the request, ensuring the code hasn’t expired and that the client ID and secret match.
It will contain the following parameters:
| access_token | The token used to call the API. |
| expires_in | The amount of seconds until the access token expires. |
| token_type | Type of the token returned Bearer |
| refresh_token | The token used to refresh the access token once it has expired (only returned if the offline_access scope is requested). |
All tokens received have an associated expiry time. Access tokens and refresh tokens can be exchanged prior to expiry.
Token expiry times:
- access_token: 30 minutes
- refresh_token: 60 days.
The access token is a JWT, which can be decoded to retrieve the authentication organisation's Org ID, which will be required to make API calls (step 5). If your JWT does not contain an Organisation ID, please check that you have completed step 4 correctly by passing the parameters in the body (not as headers).
Step 5: Call the API
Make calls against the API by simply adding the following headers to your request:
| authorization | "Bearer " + access_token |
| account_id | organisation ID |
To view the API contract documentation, please click here.
Refreshing access and refresh tokens
Access tokens expire after 30 minutes. Your application can refresh an access token without user interaction by using a refresh token. You get a refresh token by requesting the offline_access scope during the initial user authorization. Refresh tokens expire after 60 days.
To refresh your access token you need to POST to the token endpoint:
https://oauth.workflowmax2.com/oauth/token
The request will require an authorization header containing your app’s client_id and client_secret
The request body will need to contain the grant type and refresh token.
| grant_type | refresh_token |
| refresh_token | Your refresh token |
| client_id | The app Client ID |
| client_secret | The app’s Client Secret |
| scope | Same scope used |
The response will contain a new access token and refresh token. You must save both tokens in order to maintain API access.