> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# List Principal items

GET https://{tenant_name}.benchling.com/api/v3/protein/{protein_id}/authors/items

List Principal items.

Reference: https://docs.benchling.com/docs/api/benchling-api/protein/authors-list

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `protein_id` (string, required) — ID of the Protein.

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

## Response

### 200

OK

- `items` (list of Principal, optional)

## Errors

### 400 Protein Authors List Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Protein Authors List Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Protein Authors List Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Protein Authors List Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 500 Protein Authors List Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### Principal

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### AppInstallation

Represents an installed Benchling App on a tenant, created from an `AppDefinitionVersion`. App installations store tenant-specific configuration values and feature bindings. As a Principal, app installations can be attributed as actors for API operations and auditing.

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `configurationValues` (string, optional)
- `createdAt` (string, optional, nullable)
- `creator` (PrincipalRef, optional, nullable)
- `featureValues` (list of AssayRunFeatureValue, optional)
- `id` (string, optional)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional)

### LegacyAppInstallation

Represents a legacy (pre-App Store) Benchling App installation on a tenant. Legacy apps are configured directly with webhook URLs and configuration specs rather than through app definition versions. This type is maintained for backward compatibility with older app integrations. For new apps, see `AppInstallation`.

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `configurationSpecs` (list of AppConfigOption, optional)
- `configurationValues` (string, optional)
- `createdAt` (string, optional, nullable)
- `creator` (PrincipalRef, optional, nullable)
- `description` (string, optional, nullable)
- `featureSpecs` (list of LegacyAppInstallationFeatureSpecsItem, optional)
- `featureValues` (list of AssayRunFeatureValue, optional)
- `id` (string, optional)
- `messageSubscriptions` (list of AppMessageSubscription, optional)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional)
- `publicKey` (string, optional, nullable)
- `versionNumber` (string, optional, nullable)
- `webhookUrl` (string, optional, nullable)

### ServicePrincipal

Represents a non-human identity used for system integrations and automated processes within Benchling. Service principals act as the identity for service accounts that perform actions via APIs or background processes without human intervention. Unlike `User`, which represents a human user, ServicePrincipal is used when an integration or automated system needs to be attributed as the actor for auditing and attribution purposes. Service principals implement the Principal interface, allowing them to appear as creators or actors on domain objects. Also known as "service account" in some contexts.

- `__typename` (string, optional)
- `id` (string, optional)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional, nullable)

### User

Represents a human user in Benchling who can log in, perform actions, and own data. Users belong to one or more Organizations and may be members of Teams within those organizations. As an Owner, users can own Projects, Folders, and other resources. As a Principal, users can be assigned as reviewers, authors, or collaborators on various items. Users have attributes like email and username for identification. Users are distinct from `ServicePrincipal`, which represents non-human service accounts used for integrations.

- `__typename` (string, optional)
- `createdAt` (string, optional)
- `email` (string, optional)
- `id` (string, optional)
- `lastSeen` (string, optional, nullable)
- `modifiedAt` (string, optional)
- `name` (string, optional, nullable)
- `status` (enum, optional)
  - Allowed values: `ACTIVE`, `SUSPENDED`
- `username` (string, optional)

### PrincipalRef

- `__typename` (string, optional)
- `id` (string, optional)

### AssayRunFeatureValue

Links an app's assay run feature to a specific resource (typically a run schema) on a tenant. The featureId identifies the feature from the app definition, and resourceId references the tenant-specific resource it's bound to.

- `__typename` (string, optional)
- `featureId` (string, optional) — Developer-specified feature ID as defined in the app manifest / app definition version
- `resourceId` (string, optional, nullable)

### AppConfigOption

Defines a configuration option in an app's configuration schema. Each option has a name, optional description, and a configSpec defining the expected value type and validation.

- `__typename` (string, optional)
- `configSpec` (AppConfigOptionConfigSpec, optional) — Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, ArrayAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec
- `description` (string, optional, nullable)
- `name` (string, optional)

### LegacyAppInstallationFeatureSpecsItem

Union of CanvasFeatureSpec, AssayRunFeatureSpec, AppHomepageFeatureSpec

### AppMessageSubscription

Represents an app's subscription to a specific event type, specifying the event type and how notifications should be delivered (see `DeliveryMethod`).

- `__typename` (string, optional)
- `deliveryMethod` (enum, optional)
  - Allowed values: `WEBHOOK`, `WEBHOOK_INTERNAL`
- `type` (enum, optional)
  - Allowed values: `V2_BETA_CANVAS_CREATED`, `V2_CANVAS_CREATED`, `V2_CANVAS_USER_INTERACTED`, `V2_CANVAS_INITIALIZED`, `V2_APP_ACTIVATE_REQUESTED`, `V2_APP_DEACTIVATED`, `V2_APP_INSTALLED`, `V2_BETA_APP_CONFIGURATION_UPDATED`, `V2_ASSAY_RUN_CREATED`, `V2_ASSAY_RUN_UPDATED_FIELDS`, `V2_ENTITY_REGISTERED`, `V2_ENTRY_CREATED`, `V2_ENTRY_UPDATED_FIELDS`, `V2_ENTRY_UPDATED_REVIEW_RECORD`, `V2_REQUEST_CREATED`, `V2_REQUEST_UPDATED_FIELDS`, `V2_REQUEST_UPDATED_STATUS`, `V2_WORKFLOW_TASK_GROUP_CREATED`, `V2_WORKFLOW_TASK_GROUP_MAPPING_COMPLETED`, `V2_WORKFLOW_TASK_GROUP_UPDATED_WATCHERS`, `V2_WORKFLOW_TASK_CREATED`, `V2_WORKFLOW_TASK_UPDATED_ASSIGNEE`, `V2_WORKFLOW_TASK_UPDATED_SCHEDULED_ON`, `V2_WORKFLOW_TASK_UPDATED_STATUS`, `V2_WORKFLOW_TASK_UPDATED_FIELDS`, `V2_WORKFLOW_OUTPUT_CREATED`, `V2_WORKFLOW_OUTPUT_UPDATED_FIELDS`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_RUNNING`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_PENDING`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_SUCCEEDED`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_FAILED`, `V3_CUSTOM_ENTITY_CREATED`, `V3_CUSTOM_ENTITY_UPDATED`, `V3_DNA_OLIGO_CREATED`, `V3_DNA_OLIGO_UPDATED`, `V3_DNA_SEQUENCE_CREATED`, `V3_DNA_SEQUENCE_UPDATED`, `V3_ENTRY_CREATED`, `V3_PROJECT_CREATED`, `V3_PROJECT_UPDATED`, `V3_RNA_OLIGO_CREATED`, `V3_RNA_OLIGO_UPDATED`, `V3_RNA_SEQUENCE_CREATED`, `V3_RNA_SEQUENCE_UPDATED`, `V3_RUN_CREATED`

### AppConfigOptionConfigSpec

Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, ArrayAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec

### CanvasFeatureSpec

Defines a canvas feature for a Benchling App, which provides an embedded UI surface within entries or templates. Canvases allow apps to render custom interactive content.

- `__typename` (string, optional)
- `featureId` (string, optional)
- `locations` (list of enum, optional, nullable)
  - Allowed values: `ENTRY`, `ENTRY_TEMPLATE`, `APP_HOME`
- `name` (string, optional)

### AssayRunFeatureSpec

Defines an assay run feature for a Benchling App, allowing the app to process or generate lab automation run data.

- `__typename` (string, optional)
- `featureId` (string, optional)
- `name` (string, optional)

### AppHomepageFeatureSpec

Defines a homepage feature for a Benchling App, providing a dedicated landing page within the Benchling application for the app's functionality.

- `__typename` (string, optional)
- `featureId` (string, optional)
- `name` (string, optional)

### BooleanAppConfigSpec

Specifies that an app configuration field should accept a boolean value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### IntegerAppConfigSpec

Specifies that an app configuration field should accept an integer value.

- `__typename` (string, optional)
- `enum` (list of integer, optional, nullable) — Optional enum constraint — if present, the value must be one of these integers.
- `requiredConfig` (boolean, optional, nullable)

### FloatAppConfigSpec

Specifies that an app configuration field should accept a floating-point number.

- `__typename` (string, optional)
- `enum` (list of double, optional, nullable) — Optional enum constraint — if present, the value must be one of these floats.
- `requiredConfig` (boolean, optional, nullable)

### TextAppConfigSpec

Specifies that an app configuration field should accept a text string.

- `__typename` (string, optional)
- `enum` (list of string, optional, nullable) — Optional enum constraint — if present, the value must be one of these strings.
- `requiredConfig` (boolean, optional, nullable)

### SecureTextAppConfigSpec

Specifies that an app configuration field should accept secure (encrypted) text. Used for sensitive data like API keys or credentials.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### DateAppConfigSpec

Specifies that an app configuration field should accept a date value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### DateTimeAppConfigSpec

Specifies that an app configuration field should accept a datetime value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### JsonAppConfigSpec

Specifies that an app configuration field should accept a JSON value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### ArrayAppConfigSpec

Specifies that an app configuration field should accept an array of values.

- `__typename` (string, optional)
- `elementDefinition` (list of ArrayAppConfigOption, optional) — Defines the named config options allowed within this array and their type constraints.
- `maxElements` (integer, optional, nullable) — Maximum number of elements allowed in the array (1-500); null means no maximum.
- `minElements` (integer, optional, nullable) — Minimum number of elements allowed in the array (0-500); null means no minimum.
- `requiredConfig` (boolean, optional, nullable)

### DropdownAppConfigSpec

Specifies that an app configuration field should be a dropdown with predefined options.

- `__typename` (string, optional)
- `options` (list of AppConfigDropdownOption, optional, nullable)
- `requiredConfig` (boolean, optional, nullable)

### EntitySchemaAppConfigSpec

Specifies that an app configuration field should reference an entity schema. Kept separate from SchemaAppConfigSpec because it carries a subtype constraint.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)
- `requiredConfig` (boolean, optional, nullable)
- `subtype` (enum, optional, nullable) — Optional subtype constraint — if present, the referenced schema must be of this entity type (e.g. DNA_SEQUENCE, AA_SEQUENCE).
  - Allowed values: `AA_SEQUENCE`, `CUSTOM_ENTITY`, `DNA_OLIGO`, `DNA_SEQUENCE`, `MIXTURE`, `MOLECULE`, `RNA_OLIGO`, `RNA_SEQUENCE`

### WorkflowTaskSchemaAppConfigSpec

Specifies that an app configuration field should reference a workflow task schema. Kept separate from SchemaAppConfigSpec because it supports output field definitions.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)
- `output` (AppConfigWorkflowTaskSchemaOutput, optional, nullable) — Output field definitions for the workflow task schema.
- `requiredConfig` (boolean, optional, nullable)

### SchemaAppConfigSpec

Specifies that an app configuration field should reference one of the schema types that share a common structure: container_schema, plate_schema, location_schema, box_schema, run_schema, result_schema, legacy_request_schema, or entry_schema. The type field identifies which schema kind is required. For entity_schema use EntitySchemaAppConfigSpec; for workflow_task_schema use WorkflowTaskSchemaAppConfigSpec.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)
- `requiredConfig` (boolean, optional, nullable)
- `type` (enum, optional, nullable)
  - Allowed values: `BOX_SCHEMA`, `CONTAINER_SCHEMA`, `ENTRY_SCHEMA`, `LEGACY_REQUEST_SCHEMA`, `LOCATION_SCHEMA`, `PLATE_SCHEMA`, `RESULT_SCHEMA`, `RUN_SCHEMA`, `WORKFLOW_TASK_SCHEMA`, `AA_SEQUENCE`, `ASSAY_RESULT`, `ASSAY_RUN`, `AUTOMATION_INPUT_GENERATOR`, `AUTOMATION_OUTPUT_PROCESSOR`, `BLOB`, `BOX`, `CONTAINER`, `CUSTOM_ENTITY`, `DNA_ALIGNMENT`, `DNA_OLIGO`, `DNA_SEQUENCE`, `DROPDOWN`, `DROPDOWN_OPTION`, `ENTRY`, `FIELD`, `FOLDER`, `LEGACY_REQUEST`, `LOCATION`, `MIXTURE`, `MOLECULE`, `PLATE`, `PROJECT`, `REGISTRY`, `RNA_OLIGO`, `RNA_SEQUENCE`, `WORKFLOW_TASK_STATUS`, `WORKLIST`

### ResourceAppConfigSpec

Specifies that an app configuration field should reference a Benchling object instance. The type field identifies the kind of object required, matching the BenchlingAppType values used in app manifests (e.g. dna_sequence, folder, registry). Covers all instance reference types with no additional spec constraints beyond requiredConfig. For schema references use SchemaAppConfigSpec or EntitySchemaAppConfigSpec.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)
- `type` (enum, optional, nullable)
  - Allowed values: `BOX_SCHEMA`, `CONTAINER_SCHEMA`, `ENTRY_SCHEMA`, `LEGACY_REQUEST_SCHEMA`, `LOCATION_SCHEMA`, `PLATE_SCHEMA`, `RESULT_SCHEMA`, `RUN_SCHEMA`, `WORKFLOW_TASK_SCHEMA`, `AA_SEQUENCE`, `ASSAY_RESULT`, `ASSAY_RUN`, `AUTOMATION_INPUT_GENERATOR`, `AUTOMATION_OUTPUT_PROCESSOR`, `BLOB`, `BOX`, `CONTAINER`, `CUSTOM_ENTITY`, `DNA_ALIGNMENT`, `DNA_OLIGO`, `DNA_SEQUENCE`, `DROPDOWN`, `DROPDOWN_OPTION`, `ENTRY`, `FIELD`, `FOLDER`, `LEGACY_REQUEST`, `LOCATION`, `MIXTURE`, `MOLECULE`, `PLATE`, `PROJECT`, `REGISTRY`, `RNA_OLIGO`, `RNA_SEQUENCE`, `WORKFLOW_TASK_STATUS`, `WORKLIST`

### ArrayAppConfigOption

A config option nested within an array-type app configuration field. Structurally identical to AppConfigOption — it has a name and a configSpec — but its configSpec accepts the same config types as the top level except nested arrays (see ArrayAppConfigElementSpec).

- `__typename` (string, optional)
- `configSpec` (ArrayAppConfigOptionConfigSpec, optional) — Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec
- `description` (string, optional, nullable)
- `name` (string, optional)

### AppConfigDropdownOption

Defines an option within a dropdown-type app configuration field.

- `__typename` (string, optional)
- `description` (string, optional, nullable)
- `name` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### AppConfigFieldDefinition

Defines a field within an app configuration that references schema fields. Specifies the field name, type, whether it accepts multiple values, and whether it is required.

- `__typename` (string, optional)
- `description` (string, optional, nullable)
- `isMulti` (boolean, optional, nullable) — Whether the field must be multi-valued — null means either true or false is acceptable.
- `isRequired` (boolean, optional, nullable) — Whether the field must be required — null means either true or false is acceptable.
- `name` (string, optional)
- `requiredConfig` (boolean, optional, nullable)
- `type` (enum, optional, nullable) — Type constraint for the field — null means any type is acceptable.
  - Allowed values: `DNA_SEQUENCE_LINK`, `AA_SEQUENCE_LINK`, `CUSTOM_ENTITY_LINK`, `ENTITY_LINK`, `MIXTURE_LINK`, `MOLECULE_LINK`, `DROPDOWN`, `PART_LINK`, `AA_PART_LINK`, `TRANSLATION_LINK`, `BLOB_LINK`, `TEXT`, `LONG_TEXT`, `BATCH_LINK`, `STORAGE_LINK`, `ENTRY_LINK`, `ASSAY_REQUEST_LINK`, `ASSAY_RESULT_LINK`, `ASSAY_RUN_LINK`, `BOOLEAN`, `FLOAT`, `INTEGER`, `DATETIME`, `DATE`, `JSON`

### AppConfigWorkflowTaskSchemaOutput

Defines the output field structure for a workflow task schema configuration.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)

### ArrayAppConfigOptionConfigSpec

Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "archiveReason": "archiveReason",
      "archived": true,
      "configurationValues": "configurationValues",
      "createdAt": "createdAt",
      "featureValues": [
        {}
      ],
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/protein/protein_id/authors/items"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/protein/protein_id/authors/items';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```