Skip to main content

​
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:
Example CURL Command:
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:
Example CURL Command:
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:
Example CURL Command:
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:
Example CURL Command:

​
Deleting a Policy

Use this endpoint to delete a policy: API Endpoint:
Example CURL Command:
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:
Example CURL Command:

​
Listing All Roles

Use this endpoint to list all roles: API Endpoint:
Example CURL Command:

​
Getting Role Details

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

​
Deleting a Role

Use this endpoint to delete a role: API Endpoint:
Example CURL Command:
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:
Example CURL Command:
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:
Example CURL Command:

​
Detach a Policy from a Role

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

​
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:
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):
Example Request (assigning to a group):
Example Request (assigning to a domain):
Example Request (assigning to a service token):

​
List Role Assignments

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

​
Delete a Role Assignment

Use this endpoint to delete a role assignment: API Endpoint:
Example CURL Command:

​
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:
    Example CURL Command:
    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:
    (using the SRN which includes the access key)
  • Revoke/Delete: API Endpoint:
    You can also temporarily disable a token by detaching all its roles.