Authenticating with Qumulo's REST API

IN THIS ARTICLE 

This article outlines how you can acquire a bearer token for authenticating with Qumulo's REST API.

DETAILS

When you use the Qumulo API, you can start an authentication session by logging in. Calling the login API gives you a temporary credential called a bearer token, which the system sends together with subsequent API calls as proof that you are authenticated.

Note: Non-administrative users can log in but might not have access to certain REST API endpoints.

Qumulo API endpoints divide into three categories:

• APIs that don’t require any authentication, such as the /v1/version API endpoint
• The /v1/session/login API endpoint, which takes a username and password
• APIs that require a bearer token from the /v1/session/login API endpoint

Acquiring a Bearer Token by Using the REST API

Start an authentication session by calling the /v1/session/login API endpoint with a valid username and password. For example:

curl -k -X POST https://clusterIPorDNSname:8000/v1/session/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user", "password":"SECRET"}'

The following is the output of the command.

{ "bearer_token": "1:ATwAAABlSnp6MVZvUXhRQUViN2RCYUFVZy9zTElB..." }

Acquiring a Bearer Token by Using the Web UI

Bearer tokens can also be obtained from using the interactive API available in Qumulo Core.

1. Log in to the Qumulo Core Web UI.
2. Click API & Tools.
   
3. Click Get started by logging in.
   
4. For username, enter admin.
5. For password, enter your  password.
   
6. Click Try it!
   Successful authentication returns a 200 OK response code.
   
7. From the API Credentials field, copy the Bearer Token.
   Important:
   • To ensure another user can't use your login credentials, click Clear (or reload the page).
   • You can use your bearer token to make API requests. Your token is valid for 10 hours. To continue using an API after 10 hours elapse, you must start a new session by re-authenticating with your username and password.

Using the Bearer Token with API Calls

To make API calls, use the bearer token in your request header. In the following example, the API call lists the nodes in a single-node cluster.

curl -k -X GET https://clusterIPorDNSname:8000/v1/cluster/nodes/ \
  -H "Authorization: Bearer 1:ATwAAABlSnp6MVZvUXhRQUViN2R..."

The following is the output of the command.

{
  "id": 1,
  "node_status": "online",
  "node_name": "my-node-name", 
  "uuid": "becee591-23bc-4fec-91de-EXAMPLEb642e",
  "label": "a1:23:45:6b:70:80",
  "model_number": "Q0626",
  "capacity_in_bytes": "25605032656896", 
  "serial_number": "1234567890",
  "mac_address": "00:00:1a:00:23:bc"
}

Tip: On Linux systems, you can assign the bearer token to a variable, so that authentication doesn't require the full token value from the original login request. In the following example, we assign the bearer token to the q_prod variable.

$ q_prod="1:ATwAAABlSnp6MVZvUXhRQUViN2RCYUFVZy..."

curl -k -X GET https://clusterIPorDNSname:8000/v1/cluster/nodes/ \
  -H "Authorization: Bearer $q_prod"

ADDITIONAL RESOURCES

Getting Started with Qumulo Core REST API

Qumulo's GitHub Open Source Community