IN THIS ARTICLE
Outlines how to aquire a bearer token for authentication with Qumulo's REST API
REQUIREMENTS
- IP Address or URL for cluster running Qumulo Core
- Utility or method for placing the API call (Curl)
- Access to API & Tools page for reference
DETAILS
Qumulo API endpoints can be divided into three categories:
- APIs that don’t require any authentication, like /v1/version
- A login API at /v1/session/login, which takes a username and password
- APIs take a bearer token returned from the /v1/session/login API
When using Qumulo’s API, you will need to start an authentication session by logging in. Calling the login API gives you a temporary credential called a bearer token, which is sent along with subsequent API calls as proof that you have been authenticated.
NOTE: Non-admin users can login but may not have access to certain endpoints.
ACQUIRE A BEARER TOKEN
You start an authentication session by calling the /v1/session/login API with a valid username and password as outlined in the example below using curl.
curl -k -X POST https://clusterIPorDNSname:8000/v1/session/login -H "Content-Type: application/json" -d '{"username":"user", "password":"SECRET"}'
Output:
{ "bearer_token": "1:ATwAAABlSnp6MVZvUXhRQUViN2RCYUFVZy9zTElBQWFNVEZBYWljME94R3hBSEpPWWtwdVpad2RrQVFBNEtnZmIgAAAAXU/JXGz/syigeb+FQ5zEzmNtk8L8GtaQ0M3UejImW4k=" }
Bearer tokens can also be obtained from using the interactive API available in Qumulo Core.
- Login to the Qumulo Core Web UI.
- Click on API & Tools.
- Select Get started by logging in beneath the page introduction to expand the Login section under Session Management.
- Type in admin for the username value and the assigned password.
- Click Try it!
- Confirm successful authentication with a 200 OK response code .
- Copy the Bearer Token value from the API Credentials box.
- To ensure another user cannot use your login credentials, click the Clear button in the API Credentials box or reload the page.
IMPORTANT! The bearer token is valid for 10 hours and can be used to make API requests. To continue using the API after 10 hours, you must re-authenticate with your username and password to start a new authentication session.
USE THE BEARER TOKEN
Now that you have a bearer token, calls to API endpoints that require authentication can be requested using the token in the request header.
Reference the example below to see how a bearer token is used to list the nodes in a single node cluster.
curl -k GET https://clusterIPorDNSname:8000/v1/cluster/nodes/ -H "Authorization: Bearer 1:ATwAAABlSnp6MVZvUXhRQUViN2RCYUFVZy9zTElBQWFNVEZBYWljME94R3hBSEpPWWtwdVpad2RrQVFBNEtnZmIgAAAAXU/JXGz/syigeb+FQ5zEzmNtk8L8GtaQ0M3UejImW4k="
Output:
{"id": 1, "node_status": "online", "node_name": "music-1",
"uuid": "becee591-23bc-4fec-91de-e4c78fab642e", "label": "f4:52:14:2b:40:30",
"model_number": "Q0626", "capacity_in_bytes": "25605032656896",
"serial_number": "XXX", "mac_address": "XX:XX:XX"}
TIP! In a UNIX shell like bash, assign the bearer token to a variable so that authentication does not require the full token value from the original login request. See the example below where our bearer token is assigned to the q_prod variable.
$ q_prod="1:ATwAAABlSnp6MVZvUXhRQUViN2RCYUFVZy9z
TElBQWFNVEZBYWljME94R3hBSEpPWWtwdVpad2RrQVFBNEtnZmIgAAAAXU/JXGz/
syigeb+FQ5zEzmNtk8L8GtaQ0M3UejImW4k="
curl -k GET https://clusterIPorDNSname:8000/v1/cluster/nodes/ -H
"Authorization: Bearer $q_prod"
RESOLUTION
You should now be able to successfully authenticate against Qumulo's REST API.
ADDITIONAL RESOURCES
Getting Started with Qumulo Core REST API
Qumulo's GitHub Open Source Community
Like what you see? Share this article with your network!
Comments
1 comment