User Token REST API - v2

NEW IN RELEASE 76

IQ Server users can create user tokens which then can be used for authentication instead of their usernames and passwords. A user token is a pair of a userCode and a passCode unique to the user, which will grant the permissions that are granted with their credentials. Further information regarding User Tokens can be found in the User Tokens page.

Creating a User Token

An IQ Server user can generate a user token for themselves by the request:

POST /api/v2/userTokens/currentUser

Using the cURL tool, the following example demonstrates a complete request to a local IQ Server to create a user token:

curl -u iq-server-user:my-secret -X POST http://localhost:8070/api/v2/userTokens/currentUser

Given a user exists with the username iq-server-user and the password my-secret is correct, a user token will be generated for the user similar to:

{
    "userCode":"NFWIevo8",
    "passCode":"wv5XosXBU5EBv1OfT31POJ0MgGGbHgbtIRYxq9k4GRgg"
}

The successful response to a user token creation as above is the only opportunity for the user to see the generated information and there is no way to retrieve the user token information afterwards. A user can only have a single user token and reset their user token by means of deleting their existing token and generating a new one.

Deleting a User Token

An IQ Server user can delete their existing user token by the request:

DELETE /api/v2/userTokens/currentUser

Using the cURL tool, the following example demonstrates a complete request to a local IQ Server to delete an existing user token:

curl -u iq-server-user:my-secret -X DELETE http://localhost:8070/api/v2/userTokens/currentUser

User Token Maintenance for System Administrators

Querying User Tokens

NEW IN RELEASE 87

A system administrator can retrieve all user tokens by sending a request to:

GET /api/v2/userTokens

Using the cURL tool, the following example demonstrates a complete request to a local IQ Server to retrieve all user tokens:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/userTokens

A sample response will resemble the following, emphasis being on the fact that passCodes are not included, but only userCodes are:

[
  {
    "userCode": "iAy35Sii"
  },
  {
    "userCode": "wSaoJ5QT"
  }
]

Querying User Tokens Within a Specific Date Range

The same endpoint supports the query parameters createdAfter and createdBefore with the expected format being yyyy-MM-dd. The following examples demonstrate retrieving user tokens created after (and including) January 1st 2019, before (yet excluding) January 31st and within January 2019, consequently:

GET /api/v2/userTokens?createdAfter=2019-01-01
GET /api/v2/userTokens?createdBefore=2019-01-31
GET /api/v2/userTokens?createdAfter=2019-01-01&createdBefore=2019-02-01

If a system administrator wanted to get user tokens created on January 15, the request to be issued should be:

GET /api/v2/userTokens?createdAfter=2019-01-15&createdBefore=2019-01-16

Purging Obsolete User Tokens by a System Administrator

A user token can become obsolete when the user that created the user token is deleted from an LDAP server. If an authentication attempt is made with an obsolete user token, the user token is deleted automatically.

A system administrator can purge obsolete user tokens by the request: 

DELETE /api/v2/userTokens/purge

Using the cURL tool, the following example demonstrates a complete request by a system administrator to a local IQ Server to delete obsolete user tokens:

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/userTokens/purge

Deleting User Tokens

NEW IN RELEASE 87

A system administrator can delete a user token by suppliying the user code of the token they want to delete:

DELETE /api/v2/userTokens/userCode/{userCode}

Using the cURL tool, the following example demonstrates a complete request by a system administrator to a local IQ Server to delete user token with user code NFWIevo8 :

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/userTokens/userCode/NFWIevo8

In case the deletion is successful, a response status 204 is returned indicating success. HTTP Status 404 Not Found is returned in case deletion is not successful due to no user token existing for the provided userCode.