Permissions and Scopes

Authentication & Authorization

All requests to the Supervised AI Testing API must be authenticated. The platform utilizes a scope-based access control model to ensure that users and automated systems can only access the resources necessary for their specific testing workflows.

Access is typically managed via API Keys or OAuth2 Bearer Tokens generated through the Supervised AI platform dashboard.

Header Format

To authenticate, include your credentials in the Authorization header of every request:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Available Scopes

The Testing API uses granular scopes to restrict access to specific endpoints and actions. When generating a token, ensure you select the minimum required scopes for your use case.

| Scope | Permission Level | Description | | :--- | :--- | :--- | | testing:read | Read-only | Allows fetching test results, viewing test suite configurations, and listing active test runs. | | testing:write | Write | Allows initiating new test runs, uploading test datasets, and updating existing test configurations. | | testing:delete | Admin/Maintainer | Allows the deletion of historical test data, results, and custom test suites. | | suites:manage | Admin | Full control over the creation, modification, and deletion of reusable test suites across the project. |

Granular Access Levels

The following table maps common API operations to the required scopes:

Test Execution

| Endpoint | Method | Required Scope | | :--- | :--- | :--- | | /v1/tests/run | POST | testing:write | | /v1/tests/stop/{id} | POST | testing:write | | /v1/tests/results/{id} | GET | testing:read |

Suite Management

| Endpoint | Method | Required Scope | | :--- | :--- | :--- | | /v1/suites | GET | testing:read | | /v1/suites | POST | suites:manage | | /v1/suites/{id} | DELETE | suites:manage |

Implementation Example

When integrating the Testing API into a CI/CD pipeline, it is recommended to use a token limited to testing:write and testing:read. This prevents accidental deletion of project data while allowing the pipeline to trigger tests and poll for results.

Example Request (Node.js)

const axios = require('axios');

async function triggerTest() {
  try {
    const response = await axios.post('https://api.supervised.ai/v1/tests/run', {
      suite_id: "suite_7890",
      model_version: "v2.1-stable"
    }, {
      headers: {
        'Authorization': `Bearer ${process.env.SUPERVISED_AI_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    console.log('Test Started:', response.data.id);
  } catch (error) {
    console.error('Authorization failed or insufficient scopes.');
  }
}

Security Best Practices

• Principle of Least Privilege: Do not use tokens with suites:manage or testing:delete scopes in automated scripts unless explicitly required.
• Token Rotation: Regularly rotate API keys used in production or CI environments.
• Environment Variables: Never hardcode tokens in your source code. Use secret management tools or environment variables.