Vertesia Access Control Entries API

openapi: 3.2.0
info:
  title: Vertesia Access Control Entries API
  version: 1.6.0-dev.20261019.172735Z
  x-api-version: '20260803'
  description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
  contact:
    name: Vertesia
    url: https://vertesiahq.com/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-scalar-sdk-installation:
  - lang: Node
    description: 'Install the **Vertesia Client** from npm:'
    source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
  description: Vertesia API
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      - jp1
      description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Access Control Entries
  description: Access Control Entry endpoints manage account-, project-, and app-level role assignments for users, groups, and API keys.
paths:
  /iam/aces/project:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ListProjectAccessControlEntries
      tags:
      - Access Control Entries
      summary: List project-scoped access control entries
      description: 'Lists all ACEs scoped to the current project, including regular project ACEs and dynamic (content_set/principal_set) ACEs.


        **Required permissions:** `account:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:read
      parameters: []
      responses:
        '200':
          description: Project-scoped access control entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessControlEntryArray'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:read
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/access-control.ts
        className: AccessControlResource
        methodName: listProjectAces
  /iam/aces:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ListAccessControlEntries
      tags:
      - Access Control Entries
      summary: List access control entries
      description: 'Lists access control entries visible in the current account and project context.


        **Required permissions:** Any of `account:read`, `account:membership:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:read
      parameters: []
      responses:
        '200':
          description: Access control entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessControlEntryArray'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:read
      - account:membership:read
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/access-control.ts
        className: AccessControlResource
        methodName: listAces
    post:
      operationId: CreateAccessControlEntry
      tags:
      - Access Control Entries
      summary: Create an access control entry
      description: 'Creates a new access control entry for an account, project, or application resource.


        **Required permissions:** Any of `account:admin`, `account:membership:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters: []
      responses:
        '200':
          description: The created access control entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessControlEntry'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:membership:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/access-control.ts
        className: AccessControlResource
        methodName: createAce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACECreatePayload'
  /iam/aces/{aceId}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: GetAccessControlEntry
      tags:
      - Access Control Entries
      summary: Retrieve an access control entry
      description: 'Retrieves an access control entry by ID.


        **Required permissions:** Any of `account:read`, `account:membership:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:read
      parameters:
      - name: aceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested access control entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessControlEntry'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:read
      - account:membership:read
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/access-control.ts
        className: AccessControlEntryResource
        methodName: doGet
    put:
      operationId: UpdateAccessControlEntry
      tags:
      - Access Control Entries
      summary: Update an access control entry
      description: 'Updates an access control entry by ID.


        **Required permissions:** Any of `account:admin`, `account:membership:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: aceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated access control entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessControlEntry'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:membership:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/access-control.ts
        className: AccessControlEntryResource
        methodName: doPut
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACEUpdatePayload'
    delete:
      operationId: DeleteAccessControlEntry
      tags:
      - Access Control Entries
      summary: Delete an access control entry
      description: 'Deletes an access control entry by ID.


        **Required permissions:** Any of `account:admin`, `account:membership:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: aceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Access control entry deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteByIdResult'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:membership:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/access-control.ts
        className: AccessControlEntryResource
        methodName: doDelete
components:
  schemas:
    AccessControlEntry:
      type: object
      properties:
        role:
          type: string
          description: 'Role name. Typed as `string` because role names now span multiple partitions: `SystemRoles` enum values for system-domain roles, and bare strings for ABAC-domain roles (e.g. `''content:reader''`, `''content:writer''`, `''content:manager''`, `''agent_runs:reader''`). Mongoose schema validates the value against the registered role catalog via `getAllRoleNames()`.'
        resource_type:
          $ref: '#/components/schemas/AccessControlResourceType'
        resource:
          type: string
        principal_type:
          $ref: '#/components/schemas/AccessControlPrincipalType'
        principal:
          type: string
        account:
          type: string
          description: Account scope — required for principal_set/content_set ACEs.
        project:
          type: string
          description: Project scope — narrows a principal_set/content_set ACE to a single project.
        conditions:
          $ref: '#/components/schemas/AceConditions'
          description: Dynamic matching conditions for principal_set/content_set ACEs.
        tags:
          type: array
          items:
            type: string
        expires_at:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
        id:
          type: string
      required:
      - role
      - resource_type
      - resource
      - principal_type
      - principal
      - id
      additionalProperties: false
    DeleteByIdResult:
      type: object
      properties:
        id:
          type: string
      required:
      - id
      additionalProperties: false
    AccessControlEntryArray:
      type: array
      items:
        $ref: '#/components/schemas/AccessControlEntry'
    AccessControlResourceType:
      type: string
      enum:
      - project
      - environment
      - account
      - interaction
      - application
      - content_set
    ErrorResponse:
      type: object
      description: Standard JSON error response returned by the server error handler.
      properties:
        error:
          type: string
          description: HTTP status text or normalized error type.
        status:
          type: integer
          format: int32
          minimum: 400
          maximum: 599
          description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
          example: 400
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Optional additional error details.
        errorCode:
          type: string
          description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
          example: account_api_key_creation_disabled
      required:
      - error
      - status
      additionalProperties: false
    AbacScope:
      type: string
      enum:
      - document
      - collection
      - agent_run
      - shared_content
      - task
    PropertyConditionValue:
      description: A single condition value. Resolved and evaluated dynamically by token/content security code.
    AccessControlPrincipalType:
      type: string
      enum:
      - user
      - group
      - apikey
      - principal_set
    ACECreatePayload:
      type: object
      properties:
        role:
          type: string
          description: 'Role name. Typed as `string` because role names now span multiple partitions: `SystemRoles` enum values for system-domain roles, and bare strings for ABAC-domain roles (e.g. `''content:reader''`, `''content:writer''`, `''content:manager''`, `''agent_runs:reader''`). Mongoose schema validates the value against the registered role catalog via `getAllRoleNames()`.'
        resource_type:
          $ref: '#/components/schemas/AccessControlResourceType'
        resource:
          type: string
        principal_type:
          $ref: '#/components/schemas/AccessControlPrincipalType'
        principal:
          type: string
        account:
          type: string
          description: Account scope — required for principal_set/content_set ACEs.
        project:
          type: string
          description: Project scope — narrows a principal_set/content_set ACE to a single project.
        conditions:
          $ref: '#/components/schemas/AceConditions'
          description: Dynamic matching conditions for principal_set/content_set ACEs.
        tags:
          type: array
          items:
            type: string
        expires_at:
          type: string
      required:
      - role
      - resource_type
      - resource
      - principal_type
      - principal
      additionalProperties: false
    ACEUpdatePayload:
      type: object
      properties:
        role:
          type: string
          description: 'Role name. Typed as `string` because role names now span multiple partitions: `SystemRoles` enum values for system-domain roles, and bare strings for ABAC-domain roles (e.g. `''content:reader''`, `''content:writer''`, `''content:manager''`, `''agent_runs:reader''`). Mongoose schema validates the value against the registered role catalog via `getAllRoleNames()`.'
        resource_type:
          $ref: '#/components/schemas/AccessControlResourceType'
        resource:
          type: string
        principal_type:
          $ref: '#/components/schemas/AccessControlPrincipalType'
        principal:
          type: string
        account:
          type: string
          description: Account scope — required for principal_set/content_set ACEs.
        project:
          type: string
          description: Project scope — narrows a principal_set/content_set ACE to a single project.
        conditions:
          $ref: '#/components/schemas/AceConditions'
          description: Dynamic matching conditions for principal_set/content_set ACEs.
        tags:
          type: array
          items:
            type: string
        expires_at:
          type: string
      additionalProperties: false
    PropertyConditions:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/PropertyConditionValue'
    AceConditions:
      type: object
      properties:
        principal_props:
          $ref: '#/components/schemas/PropertyConditions'
          description: Property conditions matched against user/group properties at token time (PrincipalSet).
        resource_props:
          $ref: '#/components/schemas/PropertyConditions'
          description: Property conditions matched against object properties at query time (ResourceSet).
        scope:
          $ref: '#/components/schemas/AbacScope'
          description: Kind of object the `resource_props` matches. Used to disambiguate which partition's roles apply (e.g. content roles vs agent-run roles) and to form the JWT `content_security` key prefix (`{scope}:{verb}`). Absent → `'document'` (default; emits bare `read`/`write`/`delete` keys for backward compatibility).
      additionalProperties: false
      description: 'Conditions attached to an ACE for dynamic matching.

        - `principal_props`: matched against user/group properties at token time (PrincipalSet).

        - `resource_props`: matched against object properties at query time (ResourceSet).'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
          tokenUrl: https://sts.vertesia.io/oauth/token
          x-scalar-security-query:
            resource: https://api.us1.vertesia.io/api/v1
          x-scalar-security-body:
            resource: https://api.us1.vertesia.io/api/v1
          scopes:
            openid: ''
            profile: ''
            offline_access: ''
            interaction:read: ''
            interaction:write: ''
            interaction:delete: ''
            interaction:execute: ''
            run:read: ''
            run:write: ''
            environment:admin: ''
            app:manage: ''
            project:admin: ''
            project:integration_read: ''
            project:settings_write: ''
            api_key:read: ''
            account:read: ''
            account:write: ''
            account:admin: ''
            audit:read: ''
            account:member: ''
            content:read: ''
            content:read_all: ''
            content:write: ''
            content:delete: ''
            content:admin: ''
            content:superadmin: ''
            workflow:read: ''
            workflow:run: ''
            workflow:admin: ''
            workflow:superadmin: ''
            agent_run:read: ''
            task:read: ''
            task:manage: ''
x-tagGroups:
- name: Authentication
  tags:
  - Token Service
- name: GenAI
  tags:
  - Environments
  - Prompt Templates
  - Interactions
  - Interaction Runs
  - Agent Runs
- name: Content
  tags:
  - Content Object Types
  - Objects
  - Collections
  - Files
  - Rendering
  - Bulk Operations
  - Commands
- name: Data Store
  tags:
  - Data
- name: Workflow
  tags:
  - Processes
  - Tasks
  - Workflow Definitions
  - Workflow Rules
  - Workflow Runs
- name: Administration
  tags:
  - Accounts
  - Projects
  - Audit Trail
  - Costs
- name: Access Control
  tags:
  - Users
  - User Groups
  - Roles
  - Access Control Entries
  - API Keys
- name: Apps & Integrations
  tags:
  - Apps
  - OAuth Providers
  - OAuth Clients
  - OAuth Grants
  - Remote MCP Connections