Authenticating with the Safety Suite API

This article explains how to authenticate with the Safety Suite API using either User Authentication or API Authentication. 

Once authenticated, you can use the generated bearer token to make subsequent API requests.

All Safety Suite users have access to the Safety Suite API in accordance with their assigned access levels.

To obtain an API Key, you must first create a Service Account. See Creating Service Accounts and Generating API Keys

In this guide:

• Using Finder Service

• Authenticating with the API

• Parameters for /Token Requests

• Authentication Methods

• User Authentication

• API Authentication

Using Finder Service

Before authenticating, you must retrieve the correct API URL and site key for the client.

The Finder Service returns:

• webServiceURL (API URL)

• site_key (identifies the client in a multi-tenant environment)

The API URL may change with each version update of the client’s site. Always call the Finder Service before making other API requests to ensure you are using the correct endpoint.

Steps

1. Go to the Finder Service URL:
   https://finderv2.airmaestro.net/ (Swagger UI available)

2. Send a request to the Finder Service endpoint using the client site URL.

3. Note the returned webServiceURL and site_key values.

Example request:

curl -X GET --header 'Accept: application/json' 'https://finderv2.airmaestro.net/api/Finder/getSiteDetails?siteURL=test.airmaestro.com.au'

Authenticating with the API

Once you have the API URL and site key, you must generate a bearer token using the /Token endpoint.

A bearer token is required for all subsequent API requests.
 

Parameters for /Token Requests

The table below lists all available parameters for the /Token endpoint,

grant_type*	Always "password"
site_key*	The site key obtained from the Finder Service
client_id*	pwaapp for User Authentication or api for API Authentication
username	Safety Suite username
password	Safety Suite password
key_name	Name of the API Key
api_key	Generated API key value
saml_uuid	Not for integrators to use
saml_response	Not for integrators to use
refresh_token	Not for integrators to use

*Required in all requests

Example request:

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' -d 'grant_type=password&site_key=am_test&username=test&password=test&client_id=pwaapp' 'https://workerdev.airmaestro.com.au/1.1.1/token'

Authentication Methods

Safety Suite provides two authentication methods. These methods are mutually exclusive and must not be mixed in the same request.

• User Authentication (username and password)

• API Authentication (key_name and api_key)

User Authentication

Use this method when authenticating with a standard Air Maestro user account.

The username and password values are the same credentials used to log in to Air Maestro via desktop, tablet, or mobile - not API Key details.

Required Parameters

Parameter	Description
grant_type	password
site_key	From Finder Service
username	Safety Suite username
password	Safety Suite password
client_id	pwaapp

Example Parameters

grant_type=password
site_key=am_site_key
username=john.doe
password=my-pass-123-!
client_id=pwaapp

API Authentication

Use this method when authenticating with an API Key created via a Service Account.

Where to Find API Key Details

• key_name is found in Air Maestro > Setup > General > API Key Setup

• api_key is the generated value shown when creating the API Key

Required Parameters

Parameter	Description
grant_type	password
site_key	From Finder Service
key_name	Name of the API Key
api_key	Generated API Key value
client_id	api

Example Parameters

grant_type=password
site_key=am_site_key
key_name=My API Key Name
api_key=abc123==
client_id=api