Role-Based Access Control

Overview

The Testing API employs a Role-Based Access Control (RBAC) model to ensure that users and automated systems have the appropriate level of access to resources within the Supervised AI platform. Access is governed by Roles (predefined sets of permissions) and Scopes (granular access strings).

Roles and Permissions

Each API consumer is assigned a specific role that determines their broad capabilities across the environment.

| Role | Description | Typical Use Case | | :--- | :--- | :--- | | admin | Full administrative access to all resources, including user management and billing. | Organizational leads and platform owners. | | editor | Can create, modify, and delete testing suites, datasets, and configurations. | Quality Assurance engineers and Data Scientists. | | viewer | Read-only access to test results, reports, and configurations. | Stakeholders and external auditors. | | runner | Restricted access specifically for executing tests and uploading results. | CI/CD pipelines and automated service accounts. |

Permission Scopes

For more granular control, especially when using API keys or OAuth2 tokens, specific scopes can be assigned. Scopes follow the format resource:action.

Available Scopes

• tests:read: View test definitions and metadata.
• tests:write: Create or update test definitions.
• tests:execute: Trigger test runs.
• reports:read: Access generated test reports and analytics.
• datasets:read: View datasets used for supervised testing.
• datasets:write: Upload or modify training/testing datasets.

Using Access Tokens

To interact with protected endpoints, you must include a Bearer token in the Authorization header of your HTTP requests. The permissions associated with your role or API key are validated on every request.

Example Request

If you are an editor attempting to create a new test suite, your request should look like this:

POST /v1/test-suites
Host: api.supervised.ai
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "Regression Suite - LLM Performance",
  "description": "Standard latency and accuracy checks for the GPT-4 interface.",
  "tags": ["production", "critical"]
}

Response Codes

If your role or scope does not permit a specific action, the API will return a standard HTTP error code:

| Status Code | Meaning | Resolution | | :--- | :--- | :--- | | 401 Unauthorized | No valid authentication provided. | Ensure your Bearer token is valid and not expired. | | 403 Forbidden | Authenticated, but lacks sufficient permissions. | Check that your role has the required scope (e.g., tests:write). |

Internal Access Control (Internal Use Only)

Note: The internal AccessValidator component handles the mapping of JWT claims to resource permissions. While this is not directly configurable by API consumers, it ensures that scope-creep is prevented by validating the scp claim against the requested endpoint's required permission set.