All calls to the MindLink API must be performed with an authentication identity, provided in the form of a token in the request’s HTTP header collection. This token is obtained by making a one-time call to the MindLink Authentication Service with the provided credentials.
8.1 Token Management
The typical workflow of an application’s token management will be as follows:
- On start-up, obtain the applications credentials – the tuple of user credentials and agent ID.
These will typically be configured in the applications configuration file by the administrator.
Make a call to the Authentication Service to obtain a token by providing the applications credentials.
Save this token in memory.
In every other request used by the application, supply this token in the “Authorization” HTTP header.
The token will expire every hour. The application should be written to handle the expiry of the token by requesting another token from the Authentication Service, or periodically renew the token from the Authentication Service.
The Authentication service also exposes a method to return the details of a given token. This can be helpful in diagnosing and verifying token validity.
The credentials provided to the Authentication service will take two forms:
1. Agent and User pair
a. This is the typical scenario used by applications.
b. The application’s agent “agent1” will be configured with “user1” in its users collection, which in turn will be configured with the domain\bot1 account – which is an Active Directory account with password “Password1”.
c. The application will be configured to authenticate with “domain\bot1” and “Password1”, and “agent1”. It will provide these three values to the Authentication service.
d. The Authentication service will issue a token that maps to the “agent1” agent. All calls made to the Collaboration service will be mapped to and carried out by the agent1 agent.
2. Super User a. This will be used initially to configure the system.
b. Only the super user account credentials need be provided – no agent is required.
c. No calls to the Collaboration service will work with a token obtained in this way – as the token provides no mapping to an agent with which to service the request. Note that when obtaining a token via the typical Agent/User mechanism, the provided user account must map to a user configured for the given agent – otherwise an unauthorized error will be returned.
Super User and User credentials must be valid Active Directory accounts. The credentials can either be provided manually – by explicitly configuring the user name and password of the account in the configuration file of an application – or by using integrated NTLM or Kerberos authentication to use the service account credentials with which the application is running.
This mechanism is configurable in the MindLink Management Center.
Sample Code Repository
Sample code can be downloaded from https://github.com/mindlink/api-samples