User Token REST API

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 user code 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 on 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-user:my-secret -X POST http://localhost:8070/api/v2/userTokens/currentUser

Given a user exists with the username iq-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.

Checking if User has a Token

An IQ Server user can check if they have a user token issued using the following request:

GET /api/v2/userTokens/currentUser/hasToken

Using the cURL tool, the following example demonstrates a complete request to a local IQ Server to query if there is an existing token for the user:

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

A sample response will resemble the following:

{
    "userTokenExists": true
}

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

A system administrator can retrieve all user tokens for users belonging to a specific realm by sending a request to:

GET /api/v2/userTokens

An optional "realm" query parameter can be added to retrieve all user tokens for users belonging to the given security realm. If omitted, the realm will default to be the Internal realm. Supported values include "Internal", "SAML", "Crowd", and an LDAP server ID.

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

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/userTokens?realm=Internal

Each token response will include the "username" field which contains the username of the IQ user the token is associated to.

Each token response will include the "realm" field which contains the realm of the IQ user the token is associated to.

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

[
  {
    "userCode": "iAy35Sii",
    "username":  "admin",
    "realm": "Internal"
  },
  {
    "userCode": "wSaoJ5QT",
    "username": "user1",
    "realm": "Internal"
  }
]

Querying a User Token by Username

A user token with a specific username can be found by sending a request to:

GET /api/v2/userTokens/{username}

Using the cURL tool, the following example demonstrates a complete request to a local IQ Server to retrieve a user token with a given username:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/userTokens/user1?realm=Internal

A sample response will resemble the following:

{
  "userCode": "wSaoJ5QT",
  "username": "user1",
  "realm": "Internal"
}

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 1^st 2019, before (yet excluding) January 31^st 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

A system administrator can delete a user token by supplying 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.