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 Use 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/v2/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" 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.
- password
- String.
Response status codes
- 204
- User logged in successfully.
- 400
- Invalid data provided.
- 401
- Not authenticated.
- 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 Configure the LTPA token. On the IBM MQ Appliance, the LTPA token cookie name is LtpaToken2.
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/v2/loginThe 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.
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\"}"Parent topic: /login