Using Authentication Tokens for XTAM REST APIs
XTAM has always exposed APIs for every function it has, but the only way to access the API with the use of a username and password. This means that the application that calls XTAM should have this hard coded username and password to login to XTAM and ultimately call the API function like creating a new record. This is generally considered an undesirable approach because exposing the username and password like this also exposes other areas of the network that this user can access which may be completely unrelated to XTAM’s operations. Because of this and other reasons, we implemented the recommended practice of letting other applications login to XTAM using tokens.
What XTAM can do is generate tokens for a specific user where this token could be used to authenticate in XTAM on behalf of the user of which this token was generated. Then the external application that wants to communicate with XTAM should have access to XTAM by the XTAM-generated token that is saved to or hard coded into the application of function.
The advantages of using the authentication token as compared to a username and password is that the token is specific to XTAM as opposed to an actual user’s credentials. This allows the application to communicate with XTAM without hard coding a user’s password anywhere thus protecting any other areas of the network that this user can access (think of using their AD credentials which could expose any number of security issues).
XTAM provides the facilities to generate tokens for specified users, to maintain a current list of tokens and to enable (and disable) tokens invalidating them for subsequent use. XTAM also provides an option to create tokens with expiration making them invalid after a defined period of time.
To Generate API Authentication Tokens:
Login to XTAM as a System Administrator. Only System Administrator can manage Authentication Tokens.
Navigate to Administration > Tokens
Click the Generate Token button
Populate the Generate Token dialog as described below:
In the Principal field, enter the username that the token will be generated for.
In the Expiration (mins) field, enter an expiration time for the token in minutes. To generate a token that will not expire, leave this field empty.
In the Comment field, enter an optional comment related to this token.
The Token field is read-only and will display the token after it is generated.
When the Generate Token dialog is populated as needed, click the Generate button to generate the token for this user.
This token and its corresponding values will be displayed for reference in the Authentication Tokens list.
After the token(s) is generated, you may perform the following actions:
- Sort the ordering of tokens by clicking on the desired column header.
- Use the Search box to locate specific tokens.
- Export the displayed list of tokens to a CSV or PDF file.
- Click the Copy to Clipboard button to easily share the full token with your user(s) or to paste it into external applications or functions.
- Immediately Enable or Disable use of the tokens by clicking the appropriate option.
The following information is provided as columns in the Authentication Tokens report
- ID: Displays the internal XTAM ID that is associated with this token.
- Time: Displays the timestamp (MM/DD/YYYY HH:MM:SS) of when the token was generated.
- User: Displays the user that is associated to this token.
- Expiration: Displays the expiration time associated to this token. An empty field means that the token does not have an expiration time and a time with a strike though indicates that the token has expired.
- Token: Displays part of the token. Use the Copy to Clipboard button to access the full token. Disabled tokens will be shown with a strikethough.
- Comment: Displays the optional comment that was associated to this token.
- Actions Menu: Provides the following options:
- Enable/Disable: Click Disable to disable an enabled token or click Enable to enable a disabled token.
- Delete: Click Delete to delete a token.