AudaConnect BMS beta
Before making API calls, your application must be registered with Audaconnect. You’ll need to set up your application within Audaconnect and have it approved.
Once registered you will be emailed some key pieces of information to allow you to use Audaconnect. This will include your client id and secret and the Audaconnect Server endpoints.
Registering an app is covered here - please contact us for more info.
Audaconnect uses The OAuth 2.0 Authorization Framework and supports three Oauth 2.0 authentication flows. It's important to determine which authentication method suits your application best. Below are the options in more detail, and some considerations for their usage.
If your application requires access to an Audatex user's data and your application runs on a secure server, this is the right option as this grant allows you to request and obtain long-term access to a user's data. Access tokens last 30 minutes however a refresh token will allow you to obtain new tokens without the need to go back to the user.
For applications which are hosted on a secure server then the OAuth2.0 Authorisation code flow is proposed, where the user (Audatex resource owner) is prompted for Audaconnect login credentials at the first time of using your application to access Audatex resources. Once the user authenticates and gives permission, your application will be returned a code which it can exchange for an access token and refresh token. You may wish to store these tokens so you can present them again for the same user. The tokens allow user level access to Audatex services without the need for further credentials or approval from the resource owner. This allows your application to have seamless access to Audatex resources.
You will need to construct an HTTP GET to the url above, passing through the client_id, scopes and redirect_uri setup for your application on Audaconnect.
Please note that you will need to url encode all parameters, including the scopes. When muliple scopes are sent in the scope parameter, they are delimited by spaces, for exmaple: "scope=BMS.Basic BMS.Extended".
This will redirect the user's browser page to Audaconnect. Once your user logs in, Audaconnect will prompt the user to grant permissions to your application, if they haven't already.
Audaconnect will then redirect the user's browser to the redirect_uri, which is where your server receives the authorisation code.
Your redirect_uri endpoint will be requested by the user's browser. It will contain either a "code" querystring argument or an "error" argument if the user did not permit access.
If you received a code then you should exchange this for an access token by sending an HTTP POST to https://audaconnect-demo.ax-aee.co.uk/AudaAPI.Portal/OAuth20/token.
Audaconnect will respond to your POST request by returning a JSON object that contains a short-lived access token and a refresh token.
Your application should store both the access and refresh tokens in a location that is accessible between different invocations of your application. The refresh token enables your application to obtain a new access token if the one that you have expires. As such, if your application loses the refresh token, the user will need to repeat the OAuth 2.0 consent flow so that your application can obtain a new refresh token.
After obtaining an access token for a user, your application can use that token to submit authorized API requests on that user's behalf. You must specify the access token as the value of the Authorization: Bearer HTTP request header.
You can test this by including your credentials and running this phpfiddle
To refresh an access token, your application should POST an HTTP request to Audaconnect that specifies your client ID, your client secret, and the refresh token for the user. The request also sets the grant_type parameter value to refresh_token. The following example demonstrates this request:
Alternatively, you can supply the client_id and client_secret as network credentials in an Authorization: Basic HTTP request header.
The authorization server returns a JSON object that contains a new access token and a new refresh token:
This phpfiddle shows how to obtain a refreshed token.
If your application requires access to an Audatex user's data, and your application runs locally on a user's device, this is the right option as this grant ensures your client secret key is not comprimised. This grant allows you to request and obtain short-lived access to a user's data. Access tokens will expire after 30 minutes and new tokens must be requested after this.
Some Audatex APIs will not work with the implicit flow. You should make us aware if you plan to use this flow.
You will need to construct an HTTP GET to the url above, passing through the client_id, scopes and redirect_uri setup for your application on Audaconnect.
This will direct the user's browser page to Audaconnect. Once your user logs in, Audaconnect will prompt the user to grant permissions to your application, if they haven't already.
Audaconnect will then redirect the user's browser to the redirect_uri, passing the access token in ther querystring.
If the user granted access to your application, Audaconnect appends a short-lived access token in the hash fragment of the redirect URI as shown in the example below.
The response also includes the expires_in and token_type parameters. These parameters describe the lifetime of the token in seconds
and the kind of token that is being returned, respectively.
Finally, the response includes the state parameter if a state parameter was included in the original request to the authorization server (this is not mandatory but can help prevent CSRF attacks)
http://localhost/#token_type=bearer&access_token=3S1QVsUFQf582kEa&scope=ReferenceData.My&expires_in=1800&state=itsme
Note that the access token is not sent to your redirect uri server endpoint. Query string parameters which follow a hash will not be sent to the server. You will need to process the access token locally using script.
The access token can be used for 30 minutes at which point you will need to get a new token by starting the process again.
After obtaining an access token for a user, your application can use that token to submit authorized API requests on that user's behalf. You must specify the access token as the value of the Authorization: Bearer HTTP request header.
You can test this by including your credentials and running this phpfiddle