Vertesia OAuth API

openapi: 3.2.0
info:
  title: Vertesia OAuth 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
paths:
  /oauth/requests/{request_id}/grantable-projects:
    get:
      operationId: GetOAuthGrantableProjects
      tags:
      - OAuth
      summary: List projects eligible for an app OAuth request
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Eligible projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectRefArray'
        '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: []
      x-vertesia-source:
        file: ../../apps/token-server/src/api/oauth.ts
        className: OAuthResource
        methodName: retrieveGrantableProjects
  /oauth/requests/{request_id}/login:
    post:
      operationId: LoginOAuthAuthorizationRequest
      tags:
      - OAuth
      summary: Complete a login through an authorized authentication broker
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The validated authorization or consent destination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthLoginDecisionResponse'
        '404':
          description: The user must be provisioned before retrying login.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthLoginUserNotFoundResponse'
        '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: []
      x-vertesia-source:
        file: ../../apps/token-server/src/api/oauth.ts
        className: OAuthResource
        methodName: loginAuthorizationRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthLoginPayload'
components:
  schemas:
    OAuthLoginUserNotFoundResponse:
      type: object
      properties:
        error:
          type: string
          const: user_not_found
        ensure_user_url:
          type: string
      required:
      - error
      - ensure_user_url
      additionalProperties: false
    OAuthLoginDecisionResponse:
      type: object
      properties:
        redirect_url:
          type: string
        consent_url:
          type: string
      additionalProperties: false
    ProjectRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        account:
          type: string
        restricted:
          type: boolean
          description: Only set when fetching the list of projects visible to an user which is an org admin or owner. If present and true, it means that the project is not accessible to the user.(even if it visible in listing) If not present or false then the project is accessible to the user.
      required:
      - id
      - name
      - account
      additionalProperties: false
    OAuthLoginPayload:
      type: object
      properties:
        id_token:
          type: string
          minLength: 1
        account_id:
          type: string
        project_id:
          type: string
      required:
      - id_token
      additionalProperties: false
    ProjectRefArray:
      type: array
      items:
        $ref: '#/components/schemas/ProjectRef'
    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