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

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