> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abv.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Role-Based Access Controls

> Control who can access and modify your LLM observability data through hierarchical role-based permissions

Enterprise LLM observability platforms serve multiple teams with different access needs. Your security team needs read-only visibility across all projects, engineering needs full control over their projects but no access to finance's cost analysis project, and external contractors need limited access to specific datasets without seeing sensitive production data.

# How RBAC Works in ABV

ABV implements role-based access control through organizations, projects, and roles:

```mermaid theme={null}
graph TD
    Org[Organization]
    OrgRole[Org-level Role<br/>Owner/Admin/Member/Viewer/None]
    User1[User A]
    User2[User B]
    Proj1[Project 1]
    Proj2[Project 2]
    ProjRole1[Project-level Role Override<br/>Admin on Project 1]
    APIKey1[API Key 1<br/>Project 1 scoped]
    APIKey2[API Key 2<br/>Project 2 scoped]
    OrgAPIKey[Org API Key<br/>Org scoped]

    Org -->|default role| OrgRole
    Org -->|contains| User1
    Org -->|contains| User2
    Org -->|contains| Proj1
    Org -->|contains| Proj2

    User1 -.->|inherits| OrgRole
    User2 -.->|inherits| OrgRole
    User1 -.->|overrides for Project 1| ProjRole1

    Proj1 -->|has| APIKey1
    Proj2 -->|has| APIKey2
    Org -->|has| OrgAPIKey

    classDef orgClass fill:#4fc3f7,stroke:#0288d1,color:#000
    classDef roleClass fill:#ffb74d,stroke:#f57c00,color:#000
    classDef userClass fill:#81c784,stroke:#388e3c,color:#000
    classDef projectClass fill:#ba68c8,stroke:#8e24aa,color:#000
    classDef overrideClass fill:#ff8a65,stroke:#e64a19,color:#000
    classDef apiKeyClass fill:#fff176,stroke:#f57f17,color:#000

    class Org orgClass
    class OrgRole roleClass
    class User1,User2 userClass
    class Proj1,Proj2 projectClass
    class ProjRole1 overrideClass
    class APIKey1,APIKey2,OrgAPIKey apiKeyClass
```

**Hierarchy overview:**

* **Organizations** contain users and projects
* **Users** inherit organization-level roles by default
* **Project-level roles** can override organization defaults for specific projects
* **API Keys** are scoped to either a project or the entire organization

<Steps>
  <Step title="Organizations contain projects" icon="building">
    Organizations are the top-level entities in ABV's hierarchy. They contain projects, manage billing, and provide default role assignments for all members.

    All users in an organization receive a default role (Owner, Admin, Member, Viewer, or None) that applies across all projects unless overridden by project-level assignments.
  </Step>

  <Step title="Projects group observability data" icon="folder">
    Projects contain all your LLM observability data: traces, scores, prompts, datasets, and configurations. Projects enable fine-grained access control by isolating data and permissions.

    Common patterns: separate projects for production/staging environments, different teams or product lines, different customers in multi-tenant deployments, or sensitive workloads requiring restricted access.
  </Step>

  <Step title="Roles define permissions" icon="user-shield">
    Five roles provide increasing levels of access:

    * **Owner**: Complete control including billing and organization deletion
    * **Admin**: Project configuration and user management (cannot delete organization)
    * **Member**: Create and modify observability data (cannot change settings)
    * **Viewer**: Read-only access to data and dashboards
    * **None**: No default access (used when users need access to specific projects only)

    Each role maps to specific permission scopes controlling what actions users can perform.
  </Step>

  <Step title="Project-level overrides provide flexibility" icon="sliders">
    Users inherit their organization-level role by default, but you can assign project-specific roles to override this default.

    Example: A user with organization role "Viewer" can be assigned "Admin" on their team's project, giving them full control where needed while maintaining restricted access to other projects.

    To grant access to only certain projects, set the organization role to "None" and assign project-specific roles.
  </Step>

  <Step title="API keys enable programmatic access" icon="code">
    API keys authenticate programmatic access to ABV's API. They're scoped to a specific project and inherit that project's data access, but are not tied to individual users.

    Create separate API keys for different systems (CI/CD, billing, integrations) to maintain clear audit trails and enable independent key rotation without affecting other services.
  </Step>
</Steps>

# Roles and Permission Scopes

## Role Overview

<AccordionGroup>
  <Accordion title="Owner" icon="crown">
    Complete organizational control. Unrestricted access to all resources including billing, organization deletion, and project transfers.

    **For**: Founders, executives, designated administrators

    **Capabilities**: Manage billing, delete organization, transfer projects, manage members, plus all Admin/Member/Viewer permissions
  </Accordion>

  <Accordion title="Admin" icon="user-gear">
    Project configuration and user management without billing access.

    **For**: Team leads, engineering managers, technical administrators

    **Capabilities**: Create projects, manage members, manage API keys, configure integrations, plus all Member/Viewer permissions

    **Cannot**: Manage billing, delete organization
  </Accordion>

  <Accordion title="Member" icon="user">
    Create and modify observability data without configuration access.

    **For**: Engineers, data scientists, product managers

    **Capabilities**: Create/modify traces, scores, datasets, prompts, evaluations; run experiments; export data; create dashboards

    **Cannot**: Change project settings, manage users, create API keys, configure integrations
  </Accordion>

  <Accordion title="Viewer" icon="eye">
    Read-only access for monitoring and auditing.

    **For**: Security teams, auditors, executives, external stakeholders

    **Capabilities**: View traces, scores, dashboards, metrics, configurations, prompts, evaluation templates, audit logs

    **Cannot**: Modify data, export data, create resources, change settings
  </Accordion>

  <Accordion title="None" icon="ban">
    No default access. Use for project-specific assignments only.

    **For**: Contractors, external collaborators, employees working on specific projects

    **Usage**: Set organization role to "None", then assign project-specific roles (Viewer/Member/Admin) as needed
  </Accordion>
</AccordionGroup>

## Detailed Permission Scopes

<AccordionGroup>
  <Accordion title="Organization-Level Scopes" icon="building">
    Permissions available at the organization level:

    | Permission                                             | Owner | Admin | Member | Viewer | None |
    | ------------------------------------------------------ | ----- | ----- | ------ | ------ | ---- |
    | **Manage billing** (create/update billing)             | ✓     |       |        |        |      |
    | **Delete organization**                                | ✓     |       |        |        |      |
    | **Transfer projects between organizations**            | ✓     | ✓     |        |        |      |
    | **Create projects**                                    | ✓     | ✓     |        |        |      |
    | **Manage organization API keys** (CRUD)                | ✓     | ✓     |        |        |      |
    | **Update organization settings**                       | ✓     | ✓     |        |        |      |
    | **Manage organization members** (create/update/delete) | ✓     | ✓     |        |        |      |
    | **Read organization members**                          | ✓     | ✓     | ✓      |        |      |
  </Accordion>

  <Accordion title="Project-Level Scopes" icon="folder">
    Permissions available at the project level:

    | Permission                          | Owner | Admin | Member | Viewer | None |
    | ----------------------------------- | ----- | ----- | ------ | ------ | ---- |
    | **Delete project**                  | ✓     |       |        |        |      |
    | **Update project settings**         | ✓     | ✓     |        |        |      |
    | **Read project settings**           | ✓     | ✓     | ✓      | ✓      |      |
    | **Manage project members** (CUD)    | ✓     | ✓     |        |        |      |
    | **Read project members**            | ✓     | ✓     | ✓      |        |      |
    | **Manage API keys** (CUD)           | ✓     | ✓     |        |        |      |
    | **Read API keys**                   | ✓     | ✓     | ✓      |        |      |
    | **Read audit logs**                 | ✓     | ✓     |        |        |      |
    | **Manage LLM connections** (CRUD)   | ✓     | ✓     |        |        |      |
    | **Read LLM connections**            | ✓     | ✓     | ✓      | ✓      |      |
    | **Manage integrations** (CRUD)      | ✓     | ✓     |        |        |      |
    | **Manage automations** (CUD)        | ✓     | ✓     |        |        |      |
    | **Read automations**                | ✓     | ✓     | ✓      | ✓      |      |
    | **Delete traces**                   | ✓     | ✓     |        |        |      |
    | **Tag/bookmark/publish objects**    | ✓     | ✓     | ✓      |        |      |
    | **Manage datasets** (CUD)           | ✓     | ✓     | ✓      |        |      |
    | **Manage prompts** (CUD)            | ✓     | ✓     | ✓      |        |      |
    | **Read prompts**                    | ✓     | ✓     | ✓      | ✓      |      |
    | **Manage prompt experiments** (CUD) | ✓     | ✓     | ✓      |        |      |
    | **Read prompt experiments**         | ✓     | ✓     | ✓      | ✓      |      |
    | **Manage evaluations** (CUD)        | ✓     | ✓     | ✓      |        |      |
    | **Read evaluations**                | ✓     | ✓     | ✓      | ✓      |      |
    | **Manage scores** (CUD)             | ✓     | ✓     | ✓      |        |      |
    | **Read score configs**              | ✓     | ✓     | ✓      | ✓      |      |
    | **Manage annotation queues** (CUD)  | ✓     | ✓     | ✓      |        |      |
    | **Read annotation queues**          | ✓     | ✓     | ✓      | ✓      |      |
    | **Manage dashboards** (CUD)         | ✓     | ✓     | ✓      |        |      |
    | **Read dashboards**                 | ✓     | ✓     | ✓      | ✓      |      |
    | **Create batch exports**            | ✓     | ✓     | ✓      |        |      |
    | **Read batch exports**              | ✓     | ✓     | ✓      |        |      |
    | **Manage comments** (CUD)           | ✓     | ✓     | ✓      |        |      |
    | **Read comments**                   | ✓     | ✓     | ✓      | ✓      |      |

    *CUD = Create, Update, Delete*
  </Accordion>
</AccordionGroup>

# Managing Users

## Adding Users to an Organization

<Steps>
  <Step title="Navigate to organization settings" icon="gear">
    Access organization settings from the dropdown in the top navigation bar.
  </Step>

  <Step title="Invite users by email" icon="envelope">
    Enter the user's email address and assign them an organization-level role (Owner, Admin, Member, Viewer, or None).

    Users receive an email notification and can access the organization after logging in. Users without existing ABV accounts appear as "pending invites" until they sign up.
  </Step>

  <Step title="User accepts invitation" icon="user-check">
    New users sign up through the invitation email, existing users see the organization immediately after accepting the invite.
  </Step>
</Steps>

## Changing User Roles

Any user with the `organizationMembers:CUD` or `projectMembers:CUD` permission can modify user roles.

**Organization-level role changes**:

* Affect the user's default permissions across all projects
* Can only assign roles equal to or lower than your own role
* Takes effect immediately across the organization

**Project-level role changes**:

* Override the organization-level role for specific projects
* Useful for granting elevated access where needed or restricting access to sensitive projects

# Managing Projects

## Creating Projects

<Steps>
  <Step title="Verify permissions" icon="shield-check">
    Ensure you have the `projects:create` permission (available to Owners and Admins).
  </Step>

  <Step title="Create new project" icon="plus">
    Navigate to the projects section and create a new project within your ABV organization.

    Choose a descriptive name reflecting the project's purpose: environment (staging/production), team (engineering/data science), customer (for multi-tenant deployments), or use case (chatbot/analysis).
  </Step>

  <Step title="Configure initial settings" icon="sliders">
    Set up project-specific configurations: data retention policies, LLM connections, integrations, and initial team member access.
  </Step>
</Steps>

## Transferring Projects Between Organizations

Only users with the `projects:transfer_organization` permission can transfer projects.

**What gets transferred**:

* All project data (traces, scores, datasets, prompts)
* All project configurations and settings
* API keys (remain valid without interruption)
* All features continue working during and after transfer

**What changes**:

* Access control shifts to the new organization's role assignments
* Users from the original organization lose access unless they're members of the new organization
* Billing moves to the new organization

**Data integrity**: No data is lost during transfer. The project remains fully operational throughout the process.

# Project-Level Roles

By default, users inherit their organization-level role across all projects. Project-level roles provide fine-grained control when you need different permissions for different projects.

## When to Use Project-Level Roles

<AccordionGroup>
  <Accordion title="Multi-Team Organizations" icon="users">
    Different teams need different access levels within the same organization.

    **Example**: Engineering team members get Admin access on their projects but Viewer access on the finance team's cost analysis project. Finance team gets Admin on their project but None on engineering projects.
  </Accordion>

  <Accordion title="Environment Separation" icon="layer-group">
    Restrict production access while keeping staging open.

    **Example**: Set organization role to Member, then assign Admin roles only on staging projects. Production projects use the default Member role, allowing engineers to view production data but requiring senior engineers (with project-level Admin) to modify production configurations.
  </Accordion>

  <Accordion title="External Collaborators" icon="handshake">
    Grant contractors or partners access to specific projects without organization-wide visibility.

    **Example**: Set contractor organization role to None, then assign Member or Viewer roles only on the projects they're working on. They see only what they need, nothing more.
  </Accordion>

  <Accordion title="Customer Projects in Multi-Tenant Deployments" icon="building-user">
    Isolate customer data in dedicated projects with restricted access.

    **Example**: Each customer gets a dedicated project. Customer success managers get Viewer access to all customer projects, but each customer's integration uses a project-scoped API key that only accesses their specific project.
  </Accordion>
</AccordionGroup>

## How Project-Level Roles Work

**Inheritance**: Users start with their organization-level role across all projects.

**Override**: Assign a project-specific role to override the organization default for that project only.

**Independence**: Project-level roles don't affect other projects or the organization-level role.

**Complete isolation**: Setting organization role to "None" with project-specific assignments ensures users only see the projects you've explicitly granted access to.

# API Keys and Programmatic Access

API keys provide programmatic access to ABV's API for integrations, automation, and CI/CD pipelines.

## API Key Characteristics

<AccordionGroup>
  <Accordion title="Project-Scoped Access" icon="lock">
    Each API key is associated with a specific project and can only access that project's data.

    For cross-project access, use organization-scoped API keys (available to Owners and Admins) that can manage projects, users, and organization settings.
  </Accordion>

  <Accordion title="Not Tied to Users" icon="robot">
    API keys exist independently of user accounts. They remain valid when team members leave, are reassigned, or change roles.

    This independence provides stability for automated systems and clearer audit trails showing programmatic access separately from user actions.
  </Accordion>

  <Accordion title="Granular Access Control" icon="key">
    Create separate API keys for different purposes:

    * Tracing SDK integration (write traces, read prompts)
    * Billing system (read-only metrics access)
    * CI/CD pipeline (write traces to staging project only)
    * External integrations (scoped to specific resources)

    Rotate or revoke keys independently without affecting other systems.
  </Accordion>

  <Accordion title="Audit Trail" icon="file-lines">
    Audit logs distinguish between user actions and API key actions, showing which API key performed each operation.

    This separation makes it easy to track automated system behavior separately from human actions during incident investigation or compliance auditing.
  </Accordion>
</AccordionGroup>

## Managing API Keys

**Creating API keys**:

* Requires `apiKeys:CUD` permission (Owner and Admin roles)
* Specify the project the key should access
* Optionally name the key to indicate its purpose ("CI/CD Pipeline", "Billing Integration", etc.)

**Rotating API keys**:

* Create a new API key for the same project
* Update your systems to use the new key
* Delete the old key after confirming the new key works

**Revoking access**:

* Delete an API key to immediately revoke its access
* The key becomes invalid instantly across all ABV systems

[Learn more about API authentication →](/developer/platform/api-data-platform/public-api)

# Related Topics

<CardGroup cols={2}>
  <Card title="Audit Logs" icon="file-shield" href="/developer/platform/administration/audit-logs">
    Track all access and modifications for security monitoring and compliance
  </Card>

  <Card title="Data Retention" icon="clock" href="/developer/platform/administration/data-retention">
    Configure automatic data deletion policies for compliance and storage management
  </Card>

  <Card title="SCIM & Organization API" icon="users-gear" href="/developer/platform/administration/scim-org-key-scoped-api-routes">
    Automate user provisioning and project management via SCIM and organization APIs
  </Card>

  <Card title="Public API Authentication" icon="key" href="/developer/platform/api-data-platform/public-api">
    Learn how to use API keys for programmatic access to ABV
  </Card>
</CardGroup>