Log in to the z/OSMF server

You can use the POST method to log in to the z/OSMF server and obtain authentication tokens. This service creates a JSON Web Token, an LTPA token, or both, and returns the tokens to the requester.

HTTP method and URI path

POST /zosmf/services/authenticate

Where:

/zosmf/services specifies the z/OSMF REST services API.
/authenticate indicates an authentication request.

Query parameters

None.

Standard headers

Use the following standard HTTP headers with this request:

Content-Type: application/x-www-form-urlencoded: Indicates that the body of the HTTP message is a query string, consisting of name=value pairs, with each pair separated by a single ampersand (&).
Authorization: Basic <credentials>: In the context of an HTTP transaction, basic access authentication is a method for an HTTP user agent (such as a web browser) to provide a user ID and password with a request. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of ID and password, joined by a single colon (:).

Customer headers

X-CSRF-ZOSMF-HEADER: This header is required for both browser and non-browser applications. Set the header to any value or an empty string (" "). For more information, see Allowing cross-site access to REST services.

Request body

None.

Response Body

Table 1. Response body for a "log in to the z/OSMF server" request
Field name	Description
`returnCode`	Identifies the category of errors
`reasonCode`	Specified file is either not found or cannot be opened.
`message`	Describes the text information of the login result.

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Expected response

On completion, the service returns an HTTP response, which includes a status code that indicates whether your request completed. Status code 200 OK indicates success. A status code of 4nn or 5nn indicates that an error occurred.

Table 2. HTTP error response codes for a "log in to the z/OSMF server" request
HTTP error status code	Return code	Reason code	Message	Description
200	0	0	Success.	User logs in to z/OSMF server successfully.
401	8	1	Login failed. Check whether the user ID and password you use for the Basic Auth is correct, and if the user ID has the required SAF permissions.	Check whether the user ID and password you use for the Basic Auth is correct, and if the user ID has the required SAF permissions.
401	8	12	The password or passphrase is expired.	Your password or passphrase is expired. Reset the password or passphrase.
401	8	28	The user ID was revoked.	Your user ID was revoked. Contact your system administrator.
401	4	1	Login failed. The Basic Auth information in the request header is incorrect.	Correct any errors in the Basic Auth information, which is in the request header.
401	4	40	The request failed because an internal error occurred.	The request failed because an internal error occurred. Contact your system administrator.

Note:

In the General Settings > Home Page, if the option Display error details when login fails is selected, the error message indicates when a password is expired (return code 8, reason code 12), or a user ID was revoked (return code 8, reason code 28). Otherwise, if the option Display error details when login fails is not selected, an expiration or revocation error returns only the general failure message: return code 8, reason code 1. End of change

Example

In the following example, the POST method is used to log in to the z/OSMF server and obtain a JSON Web Token for the user. On completion, the token is saved as a web cookie.

Figure 1. Log in and obtain a JSON Web Token for user authentication

POST /zosmf/services/authenticate HTTP/1.1
Host: your.company.com
Referer: https://your.company.com/zosmf
Content-Type: application/x-www-form-urlencoded
cookie:"jwtToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiQmVhcmVyIiwic3ViIjoiem9zbWZh
ZCIsInVwbiI6Inpvc21mYWQiLCJncm91cHMiOlsiQ0VBR1AiLCJDUE9DVFJMIiwiQ1BPUVVFUlkiLCJJWlVBRE1JTiIsIld
MTUdSUCIsIkJNQ0ZHIl0sInJlYWxtIjoiU0FGUmVhbG0iLCJpc3MiOiJ6T1NNRiIsImV4cCI6MTU0ODg2MTM0NiwiaWF0I
joxNTQ4ODMxOTQ2fQ.Bfc9MqPSRfn-rz0Gryf_24klKD8rqZB0TWwYwYB9osdKpFDbS2wKtqKMyBx6gcPX649Uk9mh
SJlVEAz71AOgOLi9kA28rMj1mQZbimkzNzXEPPqP37HG5Ve8aGvtxCdsyPKUQAQC9DRCdB-MGLjwCaLokRI7BjtDhriwk
Kl7yBVAxOGV7Gs8arFQzsTZSlRj3VWJ-wpuOJATRUCsjBLPE7inZzxzGIlh0eyM0K_0EH6YB_RTEsdf2lSbNy36dA2aJaa
YHLw9j1-fJ1VNwMf4ipFy_x2em8bdLYIhVT0ujLtjWmd2M9dEnYGs_rt6xpKfBCILnN0yXowrrWEchEPE1Q"
cache-control: no-cache
response body: 
{"returnCode":0,"reasonCode":0,"message":"Success."}