Authenticating applications
External applications that use the API to integrate with Alloy Navigator must have a matching account in Alloy Navigator. 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 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 records associated with data in external systems.
This article describes how to authenticate applications in Alloy Navigator using application accounts. Application accounts grant full unrestricted access to all Alloy Navigator objects and workflow actions, regardless of their availability limited by security roles.
Before you begin, you must ask your Alloy Navigator administrator to create an application account in Alloy Navigator 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.
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
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 |
---|---|
|
This parameter must be set to |
|
The application ID, issued by Alloy Navigator. |
|
The application secret, issued by Alloy Navigator. |
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=client_credentials&client_id=<application ID>&client_secret=<application secret>
Request in the json format
Header:
Content-Type: application/json
Body:
{ "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 |
---|---|
|
Invalid |
|
Incorrect application ID or secret. |
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 |
---|---|
|
This parameter must be set to |
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 |
---|---|
|
The |
|
The SSO provider's ID token included into the |
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. |