Authentication with Qumulo's REST API

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 3 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:ATwAAABlSnp6MVZvUXhRQUViN2RCYUFVZy9zTElBQWFNVEZBYWljME94R3hBSEp
PWWtwdVpad2RrQVFBNEtnZmIgAAAAXU/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 response body
• Execute the Logoff method to ensure another user cannot use your login credentials once you have the "bearer_token"

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 reauthenticate 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:ATwAAABlSnp6MVZvUXhRQUViN2RCYUFVZy9z
TElBQWFNVEZBYWljME94R3hBSEpPWWtwdVpad2RrQVFBNEtnZmIgAAAAXU/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!