API User's Guide

Authenticating users

External applications that integrate with Alloy Navigator Express via the API 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:

  • Application accounts, or just applications, are used by third-party applications that run without a signed-in user present. For details, see Authenticating applications.

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

This article describes how to authenticate applications in Alloy Navigator Express using technician accounts. Depending on how you want to personalize actions that the application will perform in Alloy Navigator Express via the API, 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 Settings App Help: Managing Technician 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.

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. The API also enables user impersonation, see Performing operations on behalf of other users.

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

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 eight (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

Header

When requesting access tokens, you can use one of the following formats:

  • application/x-www-form-urlencoded

  • application/json

To indicate the data type being sent, make sure to include the respective header into the request:

  • Content-Type: application/x-www-form-urlencoded

  • Content-Type: application/json

NOTE: Content type multipart/form-data is not supported. Use application/x-www-form-urlencoded or application/json instead.

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.

Examples

The examples below show the usage of both formats and headers.

Request in the application/x-www-form-urlencoded format

Header:

Content-Type: application/x-www-form-urlencoded

Body:

grant_type=password&username=<username>&password=<password>
Request in the JSON format

Header:

Content-Type: application/json

Body:


{
	"grant_type": "password",
	"username": "<username>",
	"password": "<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 username or password.

Exchanging an SSO provider's ID token for an API Access token

The next step is to exchange the ID token obtained from your SSO provider for the API Access token. To learn how to configure SSO providers, please refer to this article.

Establishing the necessary connections between your client application and the SSO provider is a separate task. The details of how your client application interacts with the SSO provider may vary, as there are several different flows and protocols involved.

To exchange the SSO provider's token for the API Access token, send a POST request to this URL: [API URL]/externalToken.

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

By making this request, you provide the SSO provider's token in the request header Authorization: bearer <SSO provider's ID token>. The API verifies the provided token and validates its authenticity and authorization.

The request body must include the parameter grant_type=client_credentials, indicating that the token being requested is for the client (API) itself rather than a specific user.

HTTP method

POST

API URL

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

Headers

The SSO provider's token must be included into the request header Authorization: bearer <SSO provider's ID token>.

The request can be sent in one of the following formats:

  • application/x-www-form-urlencoded

  • application/json

To indicate the data type being sent, make sure to include the respective header into the request:

  • Content-Type: application/x-www-form-urlencoded

  • Content-Type: application/json

POST parameter
Parameter Description

grant_type

This parameter must be set to client_credentials.

Examples

The examples below show the usage of both formats and headers.

Request in the application/x-www-form-urlencoded format

Headers:

Authorization: bearer <SSO provider's ID token>
Content-Type: application/x-www-form-urlencoded

Body:

grant_type=client_credentials
Request in the JSON format

Headers:

Authorization: bearer <SSO provider's ID token>
Content-Type: application/json

Body:


{
    "grant_type": "client_credentials"
}
Response

Upon successful validation, the API responds with a token in JSON format, which can be used by the your application to authenticate subsequent API requests.

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

Error Description

Authorization header is not specified

The Authorization header is missing from the request.

Unable to sign in because the specified token is invalid

The SSO provider's ID token included into the Authorization header is invalid.

Unable to sign in because the specified SSO provider configuration is not recognized The server does not recognize or support the configuration of the Single Sign-On (SSO) provider specified during the sign-in process.