Vertesia OAuth Clients API

openapi: 3.2.0
info:
  title: Vertesia OAuth Clients 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: OAuth Clients
  description: OAuth Client endpoints manage clients registered against the built-in OAuth server.
paths:
  /oauth-clients:
    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: ListOAuthClients
      tags:
      - OAuth Clients
      summary: List OAuth clients
      description: 'Lists OAuth clients registered with the Vertesia OAuth server.


        **Required permissions:** `account:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters: []
      responses:
        '200':
          description: OAuth clients owned by the current account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientArray'
        '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/oauth-clients.ts
        className: OAuthClientsResource
        methodName: list
    post:
      operationId: CreateOAuthClient
      tags:
      - OAuth Clients
      summary: Create an OAuth client
      description: 'Creates a new OAuth client and returns the generated client secret for confidential clients.


        **Required permissions:** `account:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters: []
      responses:
        '200':
          description: The created OAuth client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientCreateResponse'
        '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/oauth-clients.ts
        className: OAuthClientsResource
        methodName: create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOAuthClientPayload'
  /oauth-clients/scope-metadata:
    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: GetOAuthClientScopeMetadata
      tags:
      - OAuth Clients
      summary: Retrieve OAuth client scope metadata
      description: 'Returns the OAuth scopes supported by the Vertesia OAuth server for client configuration.


        **Required permissions:** `account:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters: []
      responses:
        '200':
          description: OAuth client scope metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientScopeMetadata'
        '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/oauth-clients.ts
        className: OAuthClientsResource
        methodName: scopeMetadata
  /oauth-clients/{client_id}:
    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: GetOAuthClient
      tags:
      - OAuth Clients
      summary: Retrieve an OAuth client
      description: 'Retrieves an OAuth client by client ID.


        **Required permissions:** `account:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested OAuth client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClient'
        '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/oauth-clients.ts
        className: OAuthClientsResource
        methodName: retrieve
    put:
      operationId: UpdateOAuthClient
      tags:
      - OAuth Clients
      summary: Update an OAuth client
      description: 'Updates an existing OAuth client.


        **Required permissions:** `account:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated OAuth client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClient'
        '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/oauth-clients.ts
        className: OAuthClientsResource
        methodName: update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOAuthClientPayload'
    delete:
      operationId: DeleteOAuthClient
      tags:
      - OAuth Clients
      summary: Delete an OAuth client
      description: 'Deletes an OAuth client and associated authorization artifacts.


        **Required permissions:** `account:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth client deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '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/oauth-clients.ts
        className: OAuthClientsResource
        methodName: delete
components:
  schemas:
    OAuthTokenEndpointAuthMethod:
      type: string
      enum:
      - none
      - client_secret_post
      - client_secret_basic
      - private_key_jwt
    OAuthProjectBindingMode:
      type: string
      enum:
      - user_select
      - fixed
    OAuthClientStatus:
      type: string
      enum:
      - active
      - disabled
    UpdateOAuthClientPayload:
      type: object
      properties:
        client_name:
          type: string
        redirect_uris:
          type: array
          items:
            type: string
        grant_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthGrantType'
        response_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthResponseType'
        token_endpoint_auth_method:
          $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
        jwks_uri:
          type: string
          format: uri
        allowed_scopes:
          type: array
          items:
            type: string
        default_scopes:
          type: array
          items:
            type: string
        status:
          $ref: '#/components/schemas/OAuthClientStatus'
        revoke_previous_client_secret:
          type: boolean
          description: Immediately revoke the previous rotation secret while retaining the current secret.
        project_binding_mode:
          $ref: '#/components/schemas/OAuthProjectBindingMode'
        fixed_project_id:
          type: string
        restrict_to_owner_account:
          type: boolean
        client_secret:
          type: string
        metadata:
          type: object
          additionalProperties: true
      additionalProperties: false
    OAuthClient:
      type: object
      properties:
        app_id:
          type: string
          description: App associated with this client. Authorization requires an installation explicitly enabling this client and current user app access.
        client_name:
          type: string
        client_type:
          $ref: '#/components/schemas/OAuthClientType'
        redirect_uris:
          type: array
          items:
            type: string
        grant_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthGrantType'
        response_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthResponseType'
        token_endpoint_auth_method:
          $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
        jwks_uri:
          type: string
          format: uri
        allowed_scopes:
          type: array
          items:
            type: string
        default_scopes:
          type: array
          items:
            type: string
        registration_source:
          $ref: '#/components/schemas/OAuthRegistrationSource'
        status:
          $ref: '#/components/schemas/OAuthClientStatus'
        project_binding_mode:
          $ref: '#/components/schemas/OAuthProjectBindingMode'
        fixed_project_id:
          type: string
        restrict_to_owner_account:
          type: boolean
          description: When true (the default for new clients), the client may only be authorized for projects in its owning account/organization. Set to false to allow authorization for any project the approving user can access, regardless of account — required for OAuth/MCP clients used across organizations. The owning account itself is internal and not exposed here.
        metadata:
          type: object
          additionalProperties: true
        created_by:
          type: string
        client_secret_configured:
          type: boolean
        created_at:
          type: string
        updated_at:
          type: string
        client_id:
          type: string
      required:
      - client_name
      - client_type
      - redirect_uris
      - grant_types
      - response_types
      - token_endpoint_auth_method
      - allowed_scopes
      - registration_source
      - status
      - project_binding_mode
      - created_at
      - updated_at
      - client_id
      additionalProperties: false
    OAuthClientScopeMetadata:
      type: object
      properties:
        supported_scopes:
          type: array
          items:
            type: string
      required:
      - supported_scopes
      additionalProperties: false
    OAuthResponseType:
      type: string
      const: code
    OAuthRegistrationSource:
      type: string
      enum:
      - admin
      - dynamic
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      additionalProperties: false
    OAuthGrantType:
      type: string
      enum:
      - authorization_code
      - refresh_token
      - urn:ietf:params:oauth:grant-type:device_code
      - urn:ietf:params:oauth:grant-type:token-exchange
    OAuthClientArray:
      type: array
      items:
        $ref: '#/components/schemas/OAuthClient'
    OAuthClientCreateResponse:
      type: object
      properties:
        app_id:
          type: string
          description: App associated with this client. Authorization requires an installation explicitly enabling this client and current user app access.
        client_name:
          type: string
        client_type:
          $ref: '#/components/schemas/OAuthClientType'
        redirect_uris:
          type: array
          items:
            type: string
        grant_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthGrantType'
        response_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthResponseType'
        token_endpoint_auth_method:
          $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
        jwks_uri:
          type: string
          format: uri
        allowed_scopes:
          type: array
          items:
            type: string
        default_scopes:
          type: array
          items:
            type: string
        registration_source:
          $ref: '#/components/schemas/OAuthRegistrationSource'
        status:
          $ref: '#/components/schemas/OAuthClientStatus'
        project_binding_mode:
          $ref: '#/components/schemas/OAuthProjectBindingMode'
        fixed_project_id:
          type: string
        restrict_to_owner_account:
          type: boolean
          description: When true (the default for new clients), the client may only be authorized for projects in its owning account/organization. Set to false to allow authorization for any project the approving user can access, regardless of account — required for OAuth/MCP clients used across organizations. The owning account itself is internal and not exposed here.
        metadata:
          type: object
          additionalProperties: true
        created_by:
          type: string
        client_secret_configured:
          type: boolean
        created_at:
          type: string
        updated_at:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
      required:
      - client_name
      - client_type
      - redirect_uris
      - grant_types
      - response_types
      - token_endpoint_auth_method
      - allowed_scopes
      - registration_source
      - status
      - project_binding_mode
      - created_at
      - updated_at
      - client_id
      additionalProperties: false
    OAuthClientType:
      type: string
      enum:
      - public
      - confidential
    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
    CreateOAuthClientPayload:
      type: object
      properties:
        client_name:
          type: string
        client_type:
          $ref: '#/components/schemas/OAuthClientType'
        redirect_uris:
          type: array
          items:
            type: string
        grant_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthGrantType'
        response_types:
          type: array
          items:
            $ref: '#/components/schemas/OAuthResponseType'
        token_endpoint_auth_method:
          $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod'
        jwks_uri:
          type: string
          format: uri
        allowed_scopes:
          type: array
          items:
            type: string
        default_scopes:
          type: array
          items:
            type: string
        project_binding_mode:
          $ref: '#/components/schemas/OAuthProjectBindingMode'
        fixed_project_id:
          type: string
        restrict_to_owner_account:
          type: boolean
        client_secret:
          type: string
        metadata:
          type: object
          additionalProperties: true
      required:
      - client_name
      - redirect_uris
      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