API User's Guide

Authenticating applications

Introduced in 8.7.3

External applications that use the API to integrate with Alloy Navigator Express must have a matching account in Alloy Navigator Express. The API supports two types of accounts, the type of account defines the security context of the API user:

  • Technician accounts are used by third-party apps that have a signed-in user present, and that user is an Alloy Navigator Express technician. Those apps act as the signed-in technician when performing workflow actions via the API. For details, see Authenticating users.

  • Application accounts, or just applications, are used by third-party apps that run without a signed-in user present. Those apps can run various maintenance or service tasks, for example routinely create or update Alloy Navigator Express records associated with data in external systems.

This article describes how to authenticate applications in Alloy Navigator Express using application accounts. Application accounts grant full unrestricted access to all Alloy Navigator Express objects and workflow actions, regardless of their availability limited by security roles.

Before you begin, you must ask your Alloy Navigator Express administrator to create an application account in Alloy Navigator Express and obtain the credentials, so the application can prove its identity when obtaining an access token. Those credentials are the Application ID and Secret, issued by Alloy Navigator Express.

INFO: For details, see Settings App Help: Managing applications.

NOTE: Your API must be configured to use Access Token authentication. You choose the authentication type when you configure the API module using the Web Configuration tool, on the User Authentication Type page. For details, see Installation Guide: Configuring the API module.

Obtaining an API Access Token

API access tokens are unique identifiers associated with your application. 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 https://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

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

POST parameters
Parameter Description

grant_type

This parameter must be set to client_credentials.

client_id

The application ID, issued by Alloy Navigator Express.

client_secret

The application secret, issued by Alloy Navigator Express.
Example

Here is an example of a correct request.

POST parameters:

grant_type: client_credentials
client_id: <application ID>
client_secret: <application secret>

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 client_credentials.

invalid_client

Incorrect application ID or secret.