z/OSMF authentication services
The z/OSMF authentication services API is provided for z/OSMF tasks and
vendor applications. This API is used to obtain or delete authentication tokens (a JSON Web Token
and an LTPA token) on the user's authentication request when logging in to or out of z/OSMF. This
API can also be used to change a z/OSMF user’s password.
| Operation | HTTP method and URI path |
|---|---|
| Log in to the z/OSMF server | POST /zosmf/services/authenticate |
| Change the user password or passphrase |
PUT /zosmf/services/authenticate |
| Log out of the z/OSMF server | DELETE /zosmf/services/authenticate |
For information about enabling the z/OSMF server to produce JSON Web Tokens, see Enabling JSON Web Token support in IBM z/OS Management Facility Configuration Guide.
Error handling
For errors that occur during the processing of a request, the API returns an appropriate HTTP
status code to the calling client. An error is indicated by a 4nn code or a
5nn code. For example, HTTP/1.1 400 Bad Request or
HTTP/1.1 500 Internal Server Error.
In addition, some errors might also include a returned JSON object that contains a message that describes the error. You can use this information to diagnose the error or provide it to IBM® Support, if required.
- HTTP 200 OK
- Request was processed successfully.
- HTTP 400 Bad request
- Request could not be processed because it contains a syntax error or an incorrect parameter.
- HTTP 401 Unauthorized
- Request could not be processed because the client is not authorized. This status is returned if the request contained an incorrect user ID or password, or both, or the client did not authenticate to z/OSMF.
- HTTP 500 Internal server error
- Server encountered an error. See the response body for a JSON object with information about the error.
- HTTP 503 Service unavailable
- Server is not available.
Error logging
Errors from the z/OSMF authentication services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM Support, if required. For information about working with z/OSMF log files, see z/OSMF log files in IBM z/OS Management Facility Configuration Guide.