Skip to main content

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 or blank, the realm defaults to the Internal realm. Supported values include Internal, SAML, OAUTH2, Crowd, and a configured LDAP server ID or LDAP server name. LDAP server name matching ignores case and whitespace. If an LDAP server name matches a built-in realm value, use the LDAP server ID. An unrecognized realm value returns 400 Bad Request.

For self-hosted IQ Server, use GET /rest/config/ldap to list configured LDAP servers and find the LDAP server ID or LDAP server name. The response includes the LDAP server id and name values. Use id as the LDAP server ID or name as the LDAP server name. This endpoint requires the System Administrator permission, CONFIGURE_SYSTEM, also shown as “System Configuration and Users”. This permission is not available through custom roles. Unauthenticated requests return 401 Unauthorized; requests without the required permission return 403 Forbidden.

Using the cURL tool, the following example lists configured LDAP servers for a local self-hosted IQ Server:

curl -u admin:admin123 -X GET http://localhost:8070/rest/config/ldap

A sample response will resemble the following:

[
{
"id": "<ldap-server-id>",
"name": "Corporate LDAP",
"priority": 1
}
]

You can also find the LDAP server ID in the IQ Server UI. Open the LDAP server edit page. The LDAP server ID is the last segment of the browser URL, for example, .../ldap/edit/<ldapServerId>.

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

To retrieve all user tokens for users in an LDAP realm, set realm to the configured LDAP server ID or LDAP server name.

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/userTokens?realm=<ldap-server-id-or-name>"

Replace <ldap-server-id-or-name>; with the LDAP server ID or LDAP server name from the LDAP server configuration.

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}

An optional realm query parameter can be added to retrieve a user token for a user belonging to the given security realm. If omitted or blank, the realm defaults to the Internal realm. Supported values include Internal, SAML, OAUTH2, Crowd, and a configured LDAP server ID or LDAP server name. LDAP server name matching ignores case and whitespace. If an LDAP server name matches a built-in realm value, use the LDAP server ID. An unrecognized realm value returns 400 Bad Request.

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

To retrieve a user token for a user in an LDAP realm, set realm to the configured LDAP server ID or LDAP server name.

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/userTokens/user1?realm=<ldap-server-id-or-name>"

Replace user1 with the username and <ldap-server-id-or-name> with the LDAP server ID or LDAP server name from the LDAP server configuration.

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 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

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.