This guide explains how to configure Role-Based Access Control (RBAC) in your StarTree environment using the RBAC Manager API. RBAC allows you to define granular permissions for users, groups, and service tokens.

​
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:

  1. Create a Policy: Define what actions are allowed or denied on which resources.
  2. Create a Role: Create a role entity that will group permissions.
  3. Attach Policy to Role: Link the policy (permissions) to the role.
  4. 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.

  1. Start by retrieving the list of policies using the GET /api/v1/rbac-manager/policies endpoint.
  2. 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

  1. 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.

  1. 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.
  2. 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.