Authenticating the User

Updated in 8.7

The API supports two types of user authentication:

You choose the authentication type when you configure the API module using the Web Configuration tool, on the User Authentication Type page.

NOTE: Since version 8.7, the API module also supports LDAP user authentication. It enables technicians to use their domain credentials with standard authentication for signing in to web and mobile applications.

INFO: For details, see Installation Guide: Configuring the API module.

Every API user must have a matching account in Alloy Navigator Express, and that account must be a technician account. Depending on how you want to personalize actions that the API will perform in Alloy Navigator Express, you can either dedicate a special technician account for API requests or use any other technician account, associated with a real technician.

NOTE: Technician accounts are user accounts for technical staff members who work with Alloy Navigator Express. For details, see Administration Guide: Understanding accounts.

The level of access an API user has to Alloy Navigator Express is the same, whether the user accesses Alloy Navigator Express over the API or any other Alloy Navigator Express module. When access is denied, the API returns a corresponding error message.

INFO: For more information about error messages, see Getting Started.

Windows authentication

When the API is configured to use Windows authentication, requests to the API must contain authentication information to identify a Windows user account.

The easiest way to generate such requests is to send them under a Windows account that has a matching technician account in Alloy Navigator Express.

Access Token authentication

When the API is configured to use Access Token authentication, you must obtain an API access token and then specify it in the Authorization header of every request sent to the API.

Obtaining an API Access Token

API access tokens are unique identifiers associated with your Alloy Navigator Express technician account. Once you have a token, you can specify it in the Authorization header when sending requests to the API.

IMPORTANT: API access tokens are valid for 8 hours.

To obtain an access token, send a POST request to this URL: [API URL]/token.

[API URL] is the API URL, such as http://navigator.example.com/api.

TIP: To view the API URL, start the Web Configuration tool on the web server and navigate to the API module using the sidebar. The URL will be displayed in the main pane, among other configuration information.

HTTP method

POST

API URL

http://www.example.com/api/token

POST parameters
Parameter Description

grant_type

This parameter must be set to password.

username

The username of the Alloy Navigator Express technician account.

password

The password for the Alloy Navigator Express technician account.

NOTE: Accounts with Windows authentication also require specifying the password.

Example

Here is an example of a correct request.

POST parameters:

grant_type: password

username: <correct username>

password: <correct password>

Response:


{

	"access_token": "m_egolZq...zkw",

	"token_type": "bearer",

	"expires_in": 28799

}

In case of an invalid request the server returns an error message. The following errors may appear:

Error Description

unsupported_grant_type

Invalid grant_type, must be password.

invalid_grant

Incorrect login or password.