POST

Use the HTTP POST method with the login resource to log in a user and start a token-based authentication session. 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
Optional query parameters
Request headers
Request body format
Response status codes
Response headers
Response body format
Examples

Resource URL

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

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;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.; Note: If the user name specified has the MQWebUser role, ensure that the user name is entered in the same case as it is defined in the user registry. If the user name is specified in the request body in a different case to the case used in the registry, the user is 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.

[V9.0.5 Mar 2018] From IBM MQ 9.0.5, with a successful login, a security token, LtpaToken2, which is used to authenticate all further REST requests, is returned.

For IBM MQ 9.0.4 and earlier, with a successful login, two cookies are returned:

A security token, LtpaToken2, which is used to authenticate all further REST requests.
A CSRF token, csrfToken, which is used in the ibm-mq-rest-csrf-token HTTP header for REST requests that use the POST, PATCH, or DELETE HTTP methods.

Examples

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/v1/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/v1/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 required contents of the ibm-mq-rest-csrf-token HTTP header varies depending on the version of IBM MQ.

[V9.0.5 Mar 2018] From IBM MQ 9.0.5, its value can be anything including blank.

For IBM MQ 9.0.4 and earlier, after the user is logged in, the LTPA token and CSRF token 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 CSRF token is included in an ibm-mq-rest-csrf-token HTTP header. The value of the CSRF token is copied from the cookiejar.txt file:

IBM MQ 9.0.5

curl -k "https://localhost:9443/ibmmq/rest/v1/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\"}"

IBM MQ 9.0.4:

curl -k "https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue" -X POST -b c:\cookiejar.txt 
-H "ibm-mq-rest-csrf-token: 416E144A02E19E515ED5709A77FB07B4EF550FD1FE1CC44CF82C5774088A041928486A
BE9597618938B9F51D12FE4A0DFC1CB41D0C7567E9AB890F0FDB0EE43A27756F32341E712EFB82305F8603E566D3F1D041
2BADDF60AEEE656A2F3D06034FEF535BB67D52ACE265B3B6FB0D1B7F5EC83354F2118226C89FAC200724963FBA9BDA30376
DD84331933E300E543D01AEFE4AE638A6284DBA0210932CF00F376E1501615910926BA38D612682F22DC92391776B013C38
E73516CDC958F3D20661765097E4E0F4FC36DC13871C6BDE06D95E33D0EF4B41742D95F54DF962BE28FCDE04963DF77EB9A3
FEFB27CD2597415DDB9D1427602DDF517D4E07C092BEA3" -H "Content-Type: application/json" 
--data "{\"name\":\"Q1\"}"

IBM MQ 9.0.3 and earlier:

curl -k "https://localhost:9443/ibmmq/rest/v1/qmgr/QM1/queue" -X POST -b c:\cookiejar.txt 
-H "ibm-mq-rest-csrf-token: 416E144A02E19E515ED5709A77FB07B4EF550FD1FE1CC44CF82C5774088A041928486A
BE9597618938B9F51D12FE4A0DFC1CB41D0C7567E9AB890F0FDB0EE43A27756F32341E712EFB82305F8603E566D3F1D041
2BADDF60AEEE656A2F3D06034FEF535BB67D52ACE265B3B6FB0D1B7F5EC83354F2118226C89FAC200724963FBA9BDA30376
DD84331933E300E543D01AEFE4AE638A6284DBA0210932CF00F376E1501615910926BA38D612682F22DC92391776B013C38
E73516CDC958F3D20661765097E4E0F4FC36DC13871C6BDE06D95E33D0EF4B41742D95F54DF962BE28FCDE04963DF77EB9A3
FEFB27CD2597415DDB9D1427602DDF517D4E07C092BEA3" -H "Content-Type: application/json" 
--data "{\"name\":\"Q1\"}"