Vertesia Users API

openapi: 3.2.0
info:
  title: Vertesia Users 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: Users
  description: User endpoints retrieve, update, and delete account members within the current account context.
paths:
  /iam/users/identity:
    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: GetCurrentUserIdentity
      tags:
      - Users
      summary: Retrieve the current user's identity
      description: 'Returns the current user id plus the merged ABAC principal context (clearance, compartments, email, tags, properties). Conceptually an OIDC-style userinfo / identity-token endpoint: takes no parameters, derives the subject from a user or OAuth access token, and rejects principals without an underlying user (API keys, service accounts) with 400. Use this client-side to preview how PrincipalSet rules will evaluate for the signed-in user.


        **Required permissions:** `account:member`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters: []
      responses:
        '200':
          description: The current user's principal identity (id + resolved context).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrincipalIdentity'
        '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:member
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/users.ts
        className: UsersResource
        methodName: getIdentity
  /iam/users/{userId}:
    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: GetUser
      tags:
      - Users
      summary: Retrieve a user
      description: 'Retrieves a user by ID when the user belongs to the current account or is the caller.


        **Required permissions:** Any of `account:member`, `account:user:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '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:member
      - account:user:read
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/users.ts
        className: UserResource
        methodName: doGet
    put:
      operationId: UpdateUser
      tags:
      - Users
      summary: Update a user
      description: 'Updates profile fields for the caller or an administrator. Only account-role administrators may change authorization attributes (properties, clearance, or compartments).


        **Required permissions:** Any of `account:member`, `account:user:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '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:member
      - account:user:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/users.ts
        className: UserResource
        methodName: doPut
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserPayload'
    delete:
      operationId: DeleteUser
      tags:
      - Users
      summary: Delete a user
      description: 'Deletes a user from the current account. Account admins cannot delete their own user account through this endpoint.


        **Required permissions:** `account:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User 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
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/users.ts
        className: UserResource
        methodName: doDelete
components:
  schemas:
    DeleteByIdResult:
      type: object
      properties:
        id:
          type: string
      required:
      - id
      additionalProperties: false
    PrincipalIdentity:
      type: object
      properties:
        kind:
          type: string
          enum:
          - user
          - apikey
        id:
          type: string
        clearance:
          type: number
        compartments:
          type: array
          items:
            type: string
        email:
          type: string
        tags:
          type: array
          items:
            type: string
        properties:
          type: object
          additionalProperties: true
      required:
      - kind
      - id
      - clearance
      - compartments
      - tags
      - properties
      additionalProperties: false
      description: 'Response shape of the `/iam/users/identity` endpoint: the current principal''s full ABAC context — its `kind` (always `user` here), `id`, and the merged BLP attributes a rule can reference through `$principal.*`.'
    UpdateUserPayload:
      type: object
      properties:
        name:
          type: string
        username:
          type: string
        picture:
          type: string
        language:
          type: string
        phone:
          type: string
        last_selected_account:
          type: string
        properties:
          type: object
          additionalProperties: true
          description: Custom properties for dynamic permission matching
        clearance:
          type: number
          description: BLP clearance level — determines max document sensitivity the user can access
        compartments:
          type: array
          items:
            type: string
          description: Compartments the user belongs to — restricts access to documents in matching compartments
      additionalProperties: false
    User:
      type: object
      properties:
        id:
          type: string
        externalId:
          type: string
        email:
          type: string
        name:
          type: string
        username:
          type: string
        picture:
          type: string
        language:
          type: string
        phone:
          type: string
        sign_in_provider:
          type: string
        last_selected_account:
          type: string
        source:
          type: string
          enum:
          - firebase
          - scim
        updated_by:
          type: string
        properties:
          type: object
          additionalProperties: true
          description: Custom properties for dynamic permission matching
        clearance:
          type: number
          description: BLP clearance level — determines max document sensitivity the user can access
        compartments:
          type: array
          items:
            type: string
          description: Compartments the user belongs to — restricts access to documents in matching compartments
        annotations:
          type: array
          items:
            type: string
          description: Free-form user metadata - restricted to internal use
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update.
      required:
      - id
      - email
      - name
      - created_at
      - updated_at
      additionalProperties: false
    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
  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