Login Sessions

In the previous articles, we learned how to query the version of the HPE Composable API (also referenced here as the HPE OneView API), using the GET /rest/version call, and we discussed the importance of specifying which version of the API is expected by an application. Let us now use this to open a login session to HPE OneView. First, we can check the syntax of the login session by looking up "login" in the online help. This is what we find:

Getting a session token

From the documentation, we can see that in order to open a login session, we will need to use the POST method against the URI /rest/login-sessions. This will create (remember POST is the verb used in HTTP to create something) a session token, which we will use in the subsequent calls to the API. We will ignore the login domain information for now. We can also see in the documentation, that we will need to set three HTTP Headers:

1. X-API-Version: set to the version of the API we want to use (let's assume 200)

2. Content-Type: set to application/json, to tell the API, that the payload we will be providing is in JSON notation

3. Accept: set to application/json, to tell the API to return response in JSON notation

The payload expected by the API must contains (at minimum) the following parameters:

1. userName: set to the user name to use for authentication

2. password: set to the password for that user name

Note: Be careful, JSON is case sensitive. userName is expected here, not username, nor UserName. As a rule, the API expects lower case words, but capitalized, after the first word, if there are more than one word

HttpRequester example

To keep it simple we can use HttpRequester (a plug-in for Firefox; or POSTman a similar plug-in for Chrome) to test this. Set the following parameters and hit Submit.

The response we get is in the following form (extracted from online documentation):

The sessionID, also known as the session token is what we are looking for.

Careful with that token!

Now in order to be authorized to call any other API methods, we will need to provide the session token as another HTTP Header called Auth. So remember, we now have two HTTP Headers, which have to be provided at each call to the API: Auth and X-API-Version.

Note: You should also be aware that session tokens expire 24 hours after the last utilization.

We can now test this token and call another API method. Let us pick GET /rest/global-settings which returns the current settings of the HPE OneView appliance.

Use HttpRequester with the following parameters and press Submit:

As a quick check, remove the Auth HTTP Header, and try again. You should get a 401 Status code (Unauthorized). The details of the error clearly state that you forgot to provide an Auth header for that request.

Note: HTTP Headers are case insensitive: Auth or auth would work fine.

Cleaning up

Finally, it is best practice to delete a token when it is not needed anymore using the DELETE /rest/login-sessions. The session ID passed as an Auth Header will be deleted and will not be valid for authentication anymore. In HttpRequester, you can submit the following request:

You should get a Status of 204 (anything in the 2xx is successful) with no content for the response:

The session token was deleted. If you are curious, try to reissue the request from the HttpRequester History, which retrieved /rest/global-settings. This time you should get another 401 Authorization error. Your token is not valid anymore.

Key takeaways

Throughout the article, we have described what software will need to do in order to integrate properly with HPE OneView API and the Composable Infrastructure.

1. Query for the supported version of the API and verify compliance

2. Authenticate (using HTTP Headers: X-API-Version=version) and retrieve session token

3. Continue using the API (using HTTP Headers: X-API-Version=version and Auth=token)

4. Close the session (using HTTP Headers: X-API-Version=version and Auth=token)

   In the following articles, we will continue to investigate important concepts of the HPE OneView API.