Using the StarTree Role-Based Access Control (RBAC) API

Prerequisites

You need an Authorization Bearer token to invoke these APIs. See Generating an API Token.
Once RBAC is enabled, all access is governed by the roles and policies you set up. Ensure you assign appropriate admin privileges if needed.

Core RBAC Setup Process

Setting up RBAC generally involves these four steps:

Create a Policy: Define what actions are allowed or denied on which resources.
Create a Role: Create a role entity that will group permissions.
Attach Policy to Role: Link the policy (permissions) to the role.
Assign Role to Subject: Grant the role (and its associated permissions) to users, groups, domains, or service tokens.

Once these steps are completed, access control will be enforced based on your configuration.

Listing and Viewing Policies

Before creating a new policy, it’s often helpful to see which policies already exist in your environment.

Start by retrieving the list of policies using the GET /api/v1/rbac-manager/policies endpoint.
For any policy that you want to examine in more detail, get the policy definition using the GET /api/v1/rbac-manager/policies/{policySrn} API.

You can then decide whether to update an existing policy or create a new policy.

Working with Policies

This section covers how to list, view, create, update, and delete policies.

Listing All Policies

To get a list of all defined policies, use the following API endpoint: API Endpoint:

GET /api/v1/rbac-manager/policies

Example CURL Command:

curl --location --request GET 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/policies' \
--header 'Authorization: Bearer <Token>'

Response: A list of policy summaries, each including the policy’s name and its SRN (StarTree Resource Name).

Viewing a Specific Policy

To view the full details of a single policy, including its description and the policy document JSON, use this endpoint: API Endpoint:

GET /api/v1/rbac-manager/policies/{policySrn}

Example CURL Command:

curl --location --request GET 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/policies/srn2:policy%23<Policy-Name>' \
--header 'Authorization: Bearer <Token>'

Replace <Policy-Name> with the name part of the policy's SRN

Response: The complete details for the specified policy, including its name, description, the policy document JSON, creation timestamp, and last update timestamp.

Creating a Policy

Use this endpoint to create a policy: API Endpoint:

POST /api/v1/rbac-manager/policies

Example CURL Command:

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/policies' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "my-read-only-policy",
  "description": "Policy allowing query on myTable",
  "policyDocumentJson": "{
    \"version\": \"v1\",
    \"statements\": [
      {
        \"effect\": \"allow\",
        \"actions\": [\"query\"],
        \"resources\": [\"srn2:cluster#*:table#myTable\"]
      }
    ]
  }"
}'

Policy Document: This JSON defines the permissions. It contains statements with effect (allow/deny), actions (e.g., “query”, ”*”), and resources (e.g., “srn2:cluster#*”, “srn2:cluster#*:table#myTable”). See the custom policies documentation for syntax details, examples, and additional information.

Updating a Policy

Use this endpoint to update an existing policy: API Endpoint:

PUT /api/v1/rbac-manager/policies/{policySrn}

Example CURL Command:

curl --location --request PUT 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/policies/srn2:policy%23<Policy-Name>' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "description": "Updated policy description",
  "policyDocumentJson": "{
    \"version\": \"v1\",
    \"statements\": [
      {
        \"effect\": \"allow\",
        \"actions\": [\"query\", \"read\"],
        \"resources\": [\"srn2:cluster#*:table#myTable\"]
      }
    ]
  }"
}'

Deleting a Policy

Use this endpoint to delete a policy: API Endpoint:

DELETE /api/v1/rbac-manager/policies/{policySrn}

Example CURL Command:

curl --location --request DELETE 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/policies/srn2:policy%23<Policy-Name>' \
--header 'Authorization: Bearer <Token>'

A policy cannot be deleted if it is associated with a role.

Working with Roles

This section covers how to create, list, view, and delete roles.

Creating a Role

Use this endpoint to create a role: API Endpoint:

POST /api/v1/rbac-manager/roles

Example CURL Command:

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "table-reader-role",
  "description": "Provides read-only access to specific tables."
}'

Listing All Roles

Use this endpoint to list all roles: API Endpoint:

GET /api/v1/rbac-manager/roles

Example CURL Command:

curl --location --request GET 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles' \
--header 'Authorization: Bearer <Token>'

Getting Role Details

Use this endpoint to get details for a specific role: API Endpoint:

GET /api/v1/rbac-manager/roles/{roleSrn}

Example CURL Command:

curl --location --request GET 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>' \
--header 'Authorization: Bearer <Token>'

Deleting a Role

Use this endpoint to delete a role: API Endpoint:

DELETE /api/v1/rbac-manager/roles/{roleSrn}

Example CURL Command:

curl --location --request DELETE 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>' \
--header 'Authorization: Bearer <Token>'

A role cannot be deleted if any subjects are currently assigned to it.

Attaching Policies to Roles

This section covers how to attach policies to roles, list attached policies, and detach policies.

Attach a Policy to a Role

Use this endpoint to link a policy to a role: API Endpoint:

POST /api/v1/rbac-manager/roles/{roleSrn}/attach-policy

Example CURL Command:

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23table-reader-role/attach-policy' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "policySrn": "srn2:policy#my-read-only-policy"
}'

You can attach multiple policies to a single role by calling this API multiple times.

List Policies Attached to a Role

Use this endpoint to list all policies attached to a role: API Endpoint:

GET /api/v1/rbac-manager/roles/{roleSrn}/policies

Example CURL Command:

curl --location --request GET 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>/policies' \
--header 'Authorization: Bearer <Token>'

Detach a Policy from a Role

Use this endpoint to detach a policy from a role: API Endpoint:

POST /api/v1/rbac-manager/roles/{roleSrn}/detach-policy

Example CURL Command:

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>/detach-policy' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "policySrn": "srn2:policy#<Policy-Name>"
}'

Role Assignments

This section covers how to assign roles to subjects, list assignments, and delete assignments.

Assign a Role to a Subject

Use this endpoint to grant a role to a subject: API Endpoint:

POST /api/v1/rbac-manager/roles/{roleSrn}/create-assignment

Subject Types:

user-email: An individual user’s email address (e.g., “john.doe@acme.com”)
group: The name of a group managed in your Identity Provider (IDP) (e.g., “data-analysts”)
domain: An email domain (e.g., “acme.com”)
service-token: A service token identified by its accessKey, which is the 16 character string between st- and the following - (dash)

Example Request (assigning to a user):

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23table-reader-role/create-assignment' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "subject": "<User-Email>",
  "subjectType": "user-email"
}'

Example Request (assigning to a group):

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>/create-assignment' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "subject": "<Group-Name-from-IDP>",
  "subjectType": "group"
}'

Example Request (assigning to a domain):

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>/create-assignment' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "subject": "<Domain-Name>",
  "subjectType": "domain"
}'

Example Request (assigning to a service token):

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>/create-assignment' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "subject": "<AccessKey-from-Token>",
  "subjectType": "service-token"
}'

List Role Assignments

Use this endpoint to list all assignments for a role: API Endpoint:

GET /api/v1/rbac-manager/roles/{roleSrn}/assignments

Example CURL Command:

curl --location --request GET 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>/assignments' \
--header 'Authorization: Bearer <Token>'

Delete a Role Assignment

Use this endpoint to delete a role assignment: API Endpoint:

POST /api/v1/rbac-manager/roles/{roleSrn}/delete-assignment

Example CURL Command:

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/roles/srn2:role%23<Role-Name>/delete-assignment' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "subject": "joe@someorg.com",
  "subjectType": "user-email"
}'

Service Tokens

Service tokens act as bearer tokens for programmatic access to StarTree services (like Pinot). They consist of an access key and a secret key, formatted as st-<accesskey>-<secretkey>.

Creating and Using Service Tokens

Create Token: Use the following API endpoint: API Endpoint:

POST /api/v1/rbac-manager/service-tokens

Example CURL Command:

curl --location --request POST 'https://rbac-manager.<Your-URL>.startree.cloud/api/v1/rbac-manager/service-tokens' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "description": "<Description>"
}'

The response contains the accessKey, secretKey, and the full bearerToken.

Securely save the bearerToken and secretKey immediately; the secret key cannot be retrieved again. The accessKey is used as the identifier.

Assign Role: Use the create-assignment endpoint (detailed in the Assign a Role to a Subject section) with subjectType: “service-token” and the token’s accessKey as the subject. A token is unusable until assigned to a role.
Use Token: Use the full bearerToken (e.g., st-accesskey-secretkey) in the Authorization: Bearer <token> header for API calls.

Managing Service Tokens

Describe: API Endpoint:
```
GET /api/v1/rbac-manager/service-tokens/{tokenSrn}
```
(using the SRN which includes the access key)
Revoke/Delete: API Endpoint:
```
DELETE /api/v1/rbac-manager/service-tokens/{tokenSrn}
```
You can also temporarily disable a token by detaching all its roles.

Get Started

Ingestion

Query Data

Manage Data

Visualize Data

Manage Security

Release Notes

Reference

Using the StarTree Role-Based Access Control (RBAC) API

Prerequisites

Core RBAC Setup Process

Listing and Viewing Policies

Working with Policies

Listing All Policies

Viewing a Specific Policy

Creating a Policy

Updating a Policy

Deleting a Policy

Working with Roles

Creating a Role

Listing All Roles

Getting Role Details

Deleting a Role

Attaching Policies to Roles

Attach a Policy to a Role

List Policies Attached to a Role

Detach a Policy from a Role

Role Assignments

Assign a Role to a Subject

List Role Assignments

Delete a Role Assignment

Service Tokens

Creating and Using Service Tokens

Managing Service Tokens

Get Started

Ingestion

Query Data

Manage Data

Visualize Data

Manage Security

Release Notes

Reference

​Prerequisites

​Core RBAC Setup Process

​Listing and Viewing Policies

​Working with Policies

​Listing All Policies

​Viewing a Specific Policy

​Creating a Policy

​Updating a Policy

​Deleting a Policy

​Working with Roles

​Creating a Role

​Listing All Roles

​Getting Role Details

​Deleting a Role

​Attaching Policies to Roles

​Attach a Policy to a Role

​List Policies Attached to a Role

​Detach a Policy from a Role

​Role Assignments

​Assign a Role to a Subject

​List Role Assignments

​Delete a Role Assignment

​Service Tokens

​Creating and Using Service Tokens

​Managing Service Tokens

Prerequisites

Core RBAC Setup Process

Listing and Viewing Policies

Working with Policies

Listing All Policies

Viewing a Specific Policy

Creating a Policy

Updating a Policy

Deleting a Policy

Working with Roles

Creating a Role

Listing All Roles

Getting Role Details

Deleting a Role

Attaching Policies to Roles

Attach a Policy to a Role

List Policies Attached to a Role

Detach a Policy from a Role

Role Assignments

Assign a Role to a Subject

List Role Assignments

Delete a Role Assignment

Service Tokens

Creating and Using Service Tokens

Managing Service Tokens