REST APIs

While the Rubrik GraphQL API allows many of the operations related to Rubrik workloads and clusters, there are some operations that are only available via the appliance REST API endpoints that a Rubrik cluster provides. For example: the appliance REST API v1-6.0 .

The goal of this document is to describe the steps involved in accessing the appliance REST API endpoints using a service account. Refer to other authentication mechanisms here.

Accessing the appliance API with a service account

The following sections describe the steps involved in accessing the REST API endpoints of the appliance. The setup involves creating a service account, registering the cluster with the Rubrik domain, and retrieving the UUID of the cluster. The service account credentials and the cluster UUID are used to obtain an access token for the cluster. Subsequently, the cluster access token is used to authenticate requests to the REST API server of the cluster.

Setup

Creating a service account

Create a service account. Copy the values of the generated client credentials: CLIENT_ID and CLIENT_SECRET to use in subsequent steps.

For example:

CLIENT_ID="client|rjSOLdenk7gtFWSnSiSgX4G1SprdkF6I"
CLIENT_SECRET="qzY2TtYxPB0WYvqviWtHvK2w5P3wvQ39YXTPpIAEZCxLkSkfDCE0IV4DTWu3_o2S"

Registering the cluster

Rubrik allows the registration of a specific cluster to one and only one Rubrik domain.

Steps to register a cluster to a Rubrik domain:

Log in to the Rubrik web UI.
On the navigation bar, click Clusters.
Click the + icon to add a new cluster.
In the Copy the single-use token below section, click Copy to clipboard.
Click Done.
Log in to the Rubrik cluster using an account with administrative privileges.
Click the gear icon on the top bar of the web UI to open the Settings menu.
From the Settings menu, select System Configuration > Cluster Settings.
In Global Cluster Manager Token, paste the token from your clipboard.
In Cluster Location, type a location for the Rubrik cluster.
Click Update.

The cluster saves the values and initiates a secure connection with the Rubrik domain. After a secure connection is established, the cluster appears on the Clusters page of the Rubrik web UI.

Retrieving the cluster UUID

Use the GraphQL API to determine the UUID of the cluster connected to the Rubrik domain. The following GraphQL query retrieves the ID and lastConnectionTime for all the clusters registered with the Rubrik domain, in the increasing order of the time of registration.

{
    clusterConnection(sortBy:RegisteredAt) {
        edges{
            node{
                id,
                lastConnectionTime
            }
        }
    }
}

Sample response:

{
  "data": {
    "clusterConnection": {
      "edges": [
        {
          "node": {
            "id": "40505837-9772-4a91-a18a-db6108c66b59",
            "lastConnectionTime": "2021-11-04T11:54:00.000Z"
          }
        },
        {
          "node": {
            "id": "7bf7c2fc-dbed-4ee7-88e3-1e7fee57d02a",
            "lastConnectionTime": "2021-11-03T03:34:18.000Z"
          }
        },
        {
          "node": {
            "id": "eb1f16c6-9c9a-4825-8879-d0e0d80c88a4",
            "lastConnectionTime": "2021-10-30T07:29:38.000Z"
          }
        }
      ]
    }
  }
}

From the response, identify the cluster to access the REST API and copy the value of the "id" field for that cluster. CLUSTER_UUID refers to this value. For instance:

CLUSTER_UUID="40505837-9772-4a91-a18a-db6108c66b59"

Authentication

Use the client credentials of the service account to authenticate to the Rubrik API that generates an access token for the registered clusters. Next, use the access token to authenticate all the requests to the appliance REST API server.

Retrieving an access token for a cluster

To retrieve the access token for the registered cluster, send a POST request to the https://$account.my.rubrik-lab.com/api/cdm_client_token endpoint with the required payload.

The POST request opens a service account session and generates an access token that is valid during the session. To configure the time for which the session is valid, you can specify the time to live (TTL) period for the session using the session_ttl_minutes parameter in the POST request. The TTL value must range from 0 to 1440 minutes. When the POST request does not include the session_ttl_minutes parameter, the TTL period is set to a default value of 1440 minutes, which is equal to 24 hours.

  payload="{\"client_id\":\"$CLIENT_ID\", \
    \"client_secret\":\"$CLIENT_SECRET\", \
    \"cluster_uuid\":\"$CLUSTER_UUID\", \ 
    \"session_ttl_minutes\":\"$SESSION_TTL\"}"

  curl -X POST https://$account.my.rubrik-lab.com/api/cdm_client_token \
    --header "Content-Type: application/json" \
    --data "$payload"

Where:

$CLIENT_ID is the client ID of the service account.
$CLIENT_SECRET is the client secret of the service account.
$CLUSTER_UUID is the ID of the registered cluster.
$SESSION_TTL is the session TTL value, in minutes.
$account is the account name of your Rubrik domain.

Sample response when request is successful:

The REST API server of the Rubrik domain responds with a token and the expiration time of the token.

{
  "session": {
    "id": "009e7254-3e1b-4bef-a06a-6a0dc63cb6fe",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmNjFkN2RkNS1mN2M4LTQ3MDEtYWFiOS00ZGJmZDkxN2IwMmNfY2xpZW50fHJqU09MZGVuazdndEZXU25TaVNnWDRHMVNwcmRrRjZJIiwiaXNNZmFSZW1lbWJlclRva2VuIjpmYWxzZSwiaXNzIjoiZjYxZDdkZDUtZjdjOC00NzAxLWFhYjktNGRiZmQ5MTdiMDJjIiwiaWF0IjoxNjM2MDY4OTUxLCJqdGkiOiIwMDllNzI1NC0zZTFiLTRiZWYtYTA2YS02YTBkYzYzY2I2ZmUifQ.jTVcmpfF9jh1u4O69Yp2MGmcXOP8cxTO2TwKfXEP13U",
    "expiration": "2021-11-05T23:35:51Z"
  }
}

The "token" is the access token for sending requests to the REST API of the cluster. Save the token value as CLUSTER_ACCESS_TOKEN, as shown below:

CLUSTER_ACCESS_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmNjFkN2RkNS1mN2M4LTQ3MDEtYWFiOS00ZGJmZDkxN2IwMmNfY2xpZW50fHJqU09MZGVuazdndEZXU25TaVNnWDRHMVNwcmRrRjZJIiwiaXNNZmFSZW1lbWJlclRva2VuIjpmYWxzZSwiaXNzIjoiZjYxZDdkZDUtZjdjOC00NzAxLWFhYjktNGRiZmQ5MTdiMDJjIiwiaWF0IjoxNjM2MDY4OTUxLCJqdGkiOiIwMDllNzI1NC0zZTFiLTRiZWYtYTA2YS02YTBkYzYzY2I2ZmUifQ.jTVcmpfF9jh1u4O69Yp2MGmcXOP8cxTO2TwKfXEP13U"

Sample response when cluster is in disconnected state:

If the cluster is not connected to the Rubrik domain, the appliance API server sends the following response:

{
  "code": 500,
  "uri": "/api/cdm_client_token",
  "traceSpan": {
    "traceId": "h6tabRovn8sRY2PnOioEOg==",
    "operation": "/api/cdm_client_token",
    "spanId": "SHG3VDimBm0="
  },
  "message": "UNKNOWN: cdm cluster disconnected"
}

Using the cluster access token to access the Rubrik appliance REST API

To invoke a REST API endpoint on the appliance, authenticate to the REST API server by using the access token of the cluster, as described here (for v1-6.0).

For example:

curl -k -H "Authorization: Bearer $CLUSTER_TOKEN" -X GET\
  "https://$cluster_address/api/v1/cluster/me"

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search