| description |
|---|
API interactions require authentication. |
Access to ACAEngine is secured via OAuth2. Before interacting, your app or integration will need to authenticate and obtain a valid access token. Once authenticated, this token must accompany all requests.
This can either be included as an Authorization header (recommended):
{% tabs %} {% tab title="HTTPie" %}
http example.com/api/control/systems 'Authorization:bearer <access token>'{% endtab %}
{% tab title="cURL" %}
curl -H "Authorization: bearer <access token>" example.com/api/control/systems{% endtab %} {% endtabs %}
Or, as a query parameter:
{% tabs %} {% tab title="HTTPie" %}
http example.com/api/control/systems bearer_token==<access token>{% endtab %}
{% tab title="cURL" %}
curl "example.com/api/control/systems?bearer_token=<access token>"{% endtab %} {% endtabs %}
All applications using the ACAEngine API need to be registered in Backoffice. Details on this can be found in the Backoffice user guide.
{% page-ref page="../administration/backoffice/domains/" %}
Once registered, take note of the client_id as well as the client_secret or redirect_uri, depending on the auth flow your application will use.
Using OAuth2, a few approaches are available to obtain an access token. Here's some recommendations based on common API uses:
| Auth flow | Recommended use case |
|---|---|
| Implicit | Web, mobile and desktop apps communicating directly with the ACAEngine API. |
| Authorization Code | Web, mobile and desktop apps where your back-end communicates with the ACAEngine API on behalf of a user. |
| Password Grant | Server-to-server integration and highly trusted environments. |
Authentication and direct API access from client side applications can be safely achieved via the OAuth implicit flow without your application needing to intercept any user details. This allows federated identity services to be used and your users security and privacy to be preserved.
All interaction within this flow takes place within a client-side user agent, making it a great choice for standalone apps.
To authenticate you will need to direct users to the authorisation endpoint, accompanied by your registered application details.
{% api-method method="get" host="https://example.com" path="/auth/oauth/authorize" %} {% api-method-summary %}
{% endapi-method-summary %}
{% api-method-description %}
{% endapi-method-description %}
{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="client_id" type="string" required=true %} Application client ID {% endapi-method-parameter %}
{% api-method-parameter name="redirect_uri" type="string" required=true %} Your registered redirect URI. {% endapi-method-parameter %}
{% api-method-parameter name="response_type" type="string" required=true %} "token" {% endapi-method-parameter %}
{% api-method-parameter name="state" type="string" required=false %} A unique token, generated by your application. This will be included in the response and is recommended to avoid CSRF attacks. {% endapi-method-parameter %} {% endapi-method-path-parameters %} {% endapi-method-request %}
{% api-method-response %} {% api-method-response-example httpCode=302 %} {% api-method-response-example-description %}
{% endapi-method-response-example-description %}
{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}
Your users will then be prompted to authenticate via your configured identity provider and authorize your application. Once access is granted they will then be returned to your redirect URL with the access token included as a URI fragment.
https://<your registered redirect URI>#access_token=<token>Your application may then parse this token and use it for API requests.
{% hint style="info" %}
URI fragments can be accessed from JavaScript with document.location.hash.
{% endhint %}
{% hint style="warning" %}
If you included a state parameter (you should), this will also be returned and should be validated against your original request prior to commencing any interaction.
{% endhint %}
When building application that contains server-side components you may find a need to provide users the ability to grant your infrastructure access to interact with the ACAEngine on their behalf. This is commonly encountered if you have staff or venue app and your ACAEngine deployment is not accessible from public networks, or you may be interacting with the API asynchronously or in response to events from other systems.
As with the implicit flow, at no point does your application require direct knowledge of user credentials.
Using this flow, users first authorize your application by creating a short-lived authorization code. This is then passed to your back-end components, where it can be redeemed for an access token.
To generate the authorisation code, direct your users to the authorisation endpoint with code as the requested response type.
{% api-method method="get" host="https://example.com" path="/auth/oauth/authorize" %} {% api-method-summary %}
{% endapi-method-summary %}
{% api-method-description %}
{% endapi-method-description %}
{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="client_id" type="string" required=true %} Application client ID {% endapi-method-parameter %}
{% api-method-parameter name="redirect_uri" type="string" required=true %} Your registered redirect URI. {% endapi-method-parameter %}
{% api-method-parameter name="response_type" type="string" required=true %} "code" {% endapi-method-parameter %}
{% api-method-parameter name="state" type="string" required=false %} A unique token, generated by your application. This will be included in the response and is recommended to avoid CSRF attacks. {% endapi-method-parameter %} {% endapi-method-path-parameters %} {% endapi-method-request %}
{% api-method-response %} {% api-method-response-example httpCode=302 %} {% api-method-response-example-description %}
{% endapi-method-response-example-description %}
{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}
After authenticating and authorising your application, users will be redirected to your configured redirect URI with an authorisation code as part of the request parameters.
https://<your registered redirect URI>/?code=<authorisation code>{% hint style="warning" %}
This response will also include the state parameter if it was included in your original request. This should be validated before continuing.
{% endhint %}
Your backend infrastructure may then extract this and exchange it for an access token that can be used to perform actions as the authorising user by using the token endpoint.
{% api-method method="post" host="https://example.com" path="/auth/oauth/token" %} {% api-method-summary %}
{% endapi-method-summary %}
{% api-method-description %}
{% endapi-method-description %}
{% api-method-spec %} {% api-method-request %} {% api-method-body-parameters %} {% api-method-parameter name="grant_type" type="string" required=true %} "authorization_code" {% endapi-method-parameter %}
{% api-method-parameter name="client_id" type="string" required=true %} Application client ID. {% endapi-method-parameter %}
{% api-method-parameter name="client_secret" type="string" required=true %} Application secret. {% endapi-method-parameter %}
{% api-method-parameter name="code" type="string" required=true %} The authorization code from the previous step. {% endapi-method-parameter %}
{% api-method-parameter name="redirect_uri" type="string" required=true %} The redirect URI used in the authorization code generation. {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}
{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}
{% endapi-method-response-example-description %}
{
"access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
"created_at": 1559193360,
"expires_in": 1209600,
"refresh_token": "ac56ce17189cd8c2afc6c0fc7feeb4710bcc7985847b6f428a9a54ad6450cee0",
"scope": "public",
"token_type": "bearer"
}{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}
The Oauth2 password grant flow provides a good option for server-to-server integration, or when designing a system where direct knowledge of both user, and application secrets is acceptable.
{% hint style="danger" %} This flow should not be used as part of any components distributed to users or un-trusted endpoints. This includes usage within client side code for web apps or mobile apps, including in compiled form. {% endhint %}
This flow provides the ability to directly exchange a username and password for an access token as a single request.
{% api-method method="post" host="https://example.com" path="/auth/oauth/token" %} {% api-method-summary %}
{% endapi-method-summary %}
{% api-method-description %}
{% endapi-method-description %}
{% api-method-spec %} {% api-method-request %} {% api-method-body-parameters %} {% api-method-parameter name="grant_type" type="string" required=true %} "password" {% endapi-method-parameter %}
{% api-method-parameter name="username" type="string" required=true %} The user to authenticate as. {% endapi-method-parameter %}
{% api-method-parameter name="password" type="string" required=true %} The password to authenticate with. {% endapi-method-parameter %}
{% api-method-parameter name="authority" type="string" required=false %} The domain ID to authenticate against. {% endapi-method-parameter %}
{% api-method-parameter name="client_id" type="string" required=true %} Application client ID. {% endapi-method-parameter %}
{% api-method-parameter name="client_secret" type="string" required=true %} Application client secret. {% endapi-method-parameter %}
{% api-method-parameter name="scope" type="string" required=false %}
{% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}
{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}
{% endapi-method-response-example-description %}
{
"access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
"created_at": 1559193360,
"expires_in": 1209600,
"refresh_token": "ac56ce17189cd8c2afc6c0fc7feeb4710bcc7985847b6f428a9a54ad6450cee0",
"scope": "public",
"token_type": "bearer"
}{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}
When receiving a token, the server response will include a token expiry - expires_in - which is the number of seconds the token is valid for. By default, this is 14 days. When this period has elapsed your application will need to obtain a new access token. This can be done either by repeating the original authentication flow, or using a refresh token if provided.
Along with the access_token, successful authentication requests may also contain a refresh_token. This can be used to renew the session at any time, extending access as long as both the application registration and user are still valid.
{% api-method method="post" host="https://example.com" path="/auth/oauth/token" %} {% api-method-summary %}
{% endapi-method-summary %}
{% api-method-description %}
{% endapi-method-description %}
{% api-method-spec %} {% api-method-request %} {% api-method-body-parameters %} {% api-method-parameter name="grant_type" type="string" required=true %} "refresh_token" {% endapi-method-parameter %}
{% api-method-parameter name="refresh_token" type="string" required=true %} The refresh token to use. {% endapi-method-parameter %}
{% api-method-parameter name="client_id" type="string" required=true %} Application client ID. {% endapi-method-parameter %}
{% api-method-parameter name="client_secret" type="string" required=true %} Application client secret. {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}
{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}
{% endapi-method-response-example-description %}
{
"access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
"created_at": 1559193360,
"expires_in": 1209600,
"refresh_token": "ac56ce17189cd8c2afc6c0fc7feeb4710bcc7985847b6f428a9a54ad6450cee0",
"scope": "public",
"token_type": "bearer"
}
{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}
To end a session, applications should request a token revocation. This will invalidate the token, preventing further use.
{% api-method method="post" host="https://example.com" path="/auth/oauth/revoke" %} {% api-method-summary %}
{% endapi-method-summary %}
{% api-method-description %}
{% endapi-method-description %}
{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="token" type="string" required=true %} The token to invalidate. {% endapi-method-parameter %} {% endapi-method-path-parameters %} {% endapi-method-request %}
{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}
{% endapi-method-response-example-description %}
{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}