[V9.1.0 Jul 2018]

POST

Use the HTTP POST method with the login resource to log in a user and start a token-based authentication session for the REST API. An LTPA token is returned for the user to authenticate further REST requests.

For more information about how to use token based authentication, see Using token based authentication with the REST API.

Resource URL

https://host:port/ibmmq/rest/v2/login

Note: If you are using a version of IBM® MQ earlier than IBM MQ 9.1.5 you must use the v1 resource URL instead. That is, you must substitute v1 where the URL uses v2. For example, the first part of the URL is as follows: https://host:port/ibmmq/rest/v1/

Optional query parameters

None.

Request headers

The following headers must be sent with the request:
Content-Type
This header must be sent with a value of application/json" optionally followed by ";charset=UTF-8".

Request body format

The request body must be in JSON format in UTF-8 encoding. Within the request body attributes are defined. The following attributes can be included in the request body:
username
String.
Specifies the user name to authenticate with.
The user name that is specified must be defined within the mqweb server user registry, and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. This user name is case sensitive.
Note: If the user name specified has the MQWebUser role, ensure that the user name has the same case in the user registry as on the IBM MQ system. For example, if the user ID is defined on the IBM MQ system in uppercase, it must be defined in the registry in uppercase. If the user name is specified in different cases, the user might be authenticated by the REST API, but might not be authorized to use IBM MQ resources.
password
String.
Specifies the password of the user that is specified by the username attribute.

Response status codes

204
User logged in successfully.
400
Invalid data provided.
For example, an integer value is specified for the user name.
401
Not authenticated.
An invalid user name or password was provided.
500
Server issue or error code from IBM MQ.

Response headers

None.

Response body format

The response body is empty if the login is successful. If an error occurs, the response body contains an error message. For more information, see REST API error handling.

An LTPA security token is returned in a cookie with a successful login. This token is used to authenticate all further REST requests. By default on UNIX, Linux®, Windows and z/OS®, the cookie name starts with the prefix LtpaToken2, but the name can be changed by setting the ltpaCookieName property with the setmqweb command. For more information, see Configuring the LTPA token. On the IBM MQ Appliance, the LTPA token cookie name is LtpaToken2.

Examples

The following examples use the v2 resource URL. If you are using a version of IBM MQ earlier than IBM MQ 9.1.5 you must use the v1 resource URL instead. That is, in the resource URL, substitute v1 where the example URL uses v2.

The following example logs in a user called mqadmin with the password mqadmin. The following URL is used with the HTTP POST method:
https://localhost:9443/ibmmq/rest/v2/login
The following JSON payload is sent:
{
    "username" : "mqadmin",
    "password" : "mqadmin"
}
In cURL, the log in request might look like the following Windows example. The LTPA token is stored in the cookiejar.txt file by using the -c flag: 
curl -k "https://localhost:9443/ibmmq/rest/v2/login" -X POST 
-H "Content-Type: application/json" --data "{\"username\":\"mqadmin\",\"password\":\"mqadmin\"}" 
-c c:\cookiejar.txt

After the user is logged in, the LTPA token and ibm-mq-rest-csrf-token HTTP header are used to authenticate further requests. For example, to create a local queue, Q1, the following cURL might be used. The LTPA token is retrieved from the cookiejar.txt file by using the -b flag. The contents of the ibm-mq-rest-csrf-token HTTP header can be anything including blank.

[V9.1.0 Jul 2018] 
curl -k "https://localhost:9443/ibmmq/rest/v2/admin/qmgr/QM1/queue" -X POST 
-b c:\cookiejar.txt 
-H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" 
--data "{\"name\":\"Q1\"}"