Vertesia OAuth Providers API

openapi: 3.2.0
info:
  title: Vertesia OAuth Providers 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 Providers
  description: OAuth Provider endpoints manage project-scoped OAuth providers and the associated authorization flows and token lifecycle.
paths:
  /oauth-providers:
    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: ListOAuthProviders
      tags:
      - OAuth Providers
      summary: List OAuth providers
      description: 'Lists OAuth providers configured for the current project.


        **Required permissions:** `project:settings_write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - project:settings_write
      parameters: []
      responses:
        '200':
          description: OAuth providers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProviderArray'
        '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:
      - project:settings_write
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: list
    post:
      operationId: CreateOAuthProvider
      tags:
      - OAuth Providers
      summary: Create an OAuth provider
      description: 'Creates a new OAuth provider in the current project.


        **Required permissions:** `project:settings_write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - project:settings_write
      parameters: []
      responses:
        '200':
          description: The created OAuth provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProvider'
        '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:
      - project:settings_write
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOAuthProviderPayload'
  /oauth-providers/{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: GetOAuthProvider
      tags:
      - OAuth Providers
      summary: Retrieve an OAuth provider
      description: 'Retrieves a single OAuth provider with sensitive client secret data redacted.


        **Required permissions:** `project:settings_write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - project:settings_write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested OAuth provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProvider'
        '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:
      - project:settings_write
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: retrieve
    put:
      operationId: UpdateOAuthProvider
      tags:
      - OAuth Providers
      summary: Update an OAuth provider
      description: 'Updates an existing OAuth provider.


        **Required permissions:** `project:settings_write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - project:settings_write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated OAuth provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProvider'
        '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:
      - project:settings_write
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOAuthProviderPayload'
    delete:
      operationId: DeleteOAuthProvider
      tags:
      - OAuth Providers
      summary: Delete an OAuth provider
      description: 'Deletes an OAuth provider and associated secrets and tokens.


        **Required permissions:** `project:admin`'
      security:
      - bearerAuth: []
      - OAuth2:
        - project:admin
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth provider 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:
      - project:admin
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: delete
  /oauth-providers/{id}/authorize:
    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: AuthorizeOAuthProvider
      tags:
      - OAuth Providers
      summary: Initiate OAuth provider authorization
      description: Starts the OAuth 2.0 authorization flow for the current user.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authorization URL and state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProviderAuthorizeResponse'
        '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/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: authorize
  /oauth-providers/exchange:
    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
    post:
      operationId: ExchangeOAuthProviderCode
      tags:
      - OAuth Providers
      summary: Exchange OAuth provider authorization code
      description: Exchanges an OAuth authorization code for tokens and stores them for the current user.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters: []
      responses:
        '200':
          description: OAuth exchange 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: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: exchange
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthProviderExchangePayload'
  /oauth-providers/{id}/status:
    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: GetOAuthProviderStatus
      tags:
      - OAuth Providers
      summary: Get OAuth provider status
      description: Returns authentication status for the provider in the current project or user context.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth provider authentication status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProviderAuthStatus'
        '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/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: getStatus
  /oauth-providers/{id}/connect:
    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
    post:
      operationId: ConnectOAuthProvider
      tags:
      - OAuth Providers
      summary: Connect an OAuth provider
      description: 'Tests and establishes a client credentials connection for an OAuth provider.


        **Required permissions:** `project:settings_write`'
      security:
      - bearerAuth: []
      - OAuth2:
        - project:settings_write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth provider connection 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:
      - project:settings_write
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: connect
  /oauth-providers/{id}/token:
    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
    post:
      operationId: GetOAuthProviderToken
      tags:
      - OAuth Providers
      summary: Get an OAuth provider token
      description: Returns an access token for the configured OAuth provider.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth access token response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProviderAccessTokenResponse'
        '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/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: getToken
  /oauth-providers/{id}/disconnect:
    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
    delete:
      operationId: DisconnectOAuthProvider
      tags:
      - OAuth Providers
      summary: Disconnect an OAuth provider
      description: Revokes and deletes stored tokens for an OAuth provider.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth provider disconnect 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: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/oauth-providers.ts
        className: OAuthProvidersResource
        methodName: disconnect
components:
  schemas:
    OAuthProviderArray:
      type: array
      items:
        $ref: '#/components/schemas/OAuthProvider'
    OAuthProvider:
      type: object
      properties:
        name:
          type: string
          description: Unique name within the project (kebab-case identifier).
        display_name:
          type: string
          description: Human-readable display name.
        project:
          type: string
          description: The project this OAuth provider belongs to.
        grant_type:
          type: string
          enum:
          - authorization_code
          - client_credentials
          description: 'The OAuth 2.0 grant type to use.

            - ''authorization_code'': 3-legged flow requiring user authorization (default).

            - ''client_credentials'': 2-legged server-to-server flow using client_id + client_secret.'
        authorization_endpoint:
          type: string
          description: The OAuth 2.0 authorization endpoint URL. Only used for authorization_code flow. Optional when endpoints are discovered via .well-known (e.g. MCP servers).
        token_endpoint:
          type: string
          description: The OAuth 2.0 token endpoint URL. Optional when endpoints are discovered via .well-known (e.g. MCP servers).
        client_id:
          type: string
          description: The OAuth client ID (always required).
        has_client_secret:
          type: boolean
          description: Whether a client_secret is configured (never exposes the actual secret).
        default_scopes:
          type: array
          items:
            type: string
          description: Default scopes to request during authorization.
        use_pkce:
          type: boolean
          description: Whether to use PKCE (Proof Key for Code Exchange) in the authorization flow. Only applies to authorization_code flow. Defaults to true.
        revocation_endpoint:
          type: string
          description: Optional OAuth 2.0 revocation endpoint URL.
        created_at:
          type: string
        updated_at:
          type: string
        id:
          type: string
      required:
      - name
      - display_name
      - project
      - client_id
      - use_pkce
      - created_at
      - updated_at
      - id
      additionalProperties: false
      description: OAuth Provider as returned by the API (with id).
    OAuthProviderAccessTokenResponse:
      type: object
      properties:
        access_token:
          type: string
      required:
      - access_token
      additionalProperties: false
    CreateOAuthProviderPayload:
      type: object
      properties:
        name:
          type: string
        display_name:
          type: string
        grant_type:
          type: string
          enum:
          - authorization_code
          - client_credentials
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
          description: Optional client secret for confidential clients. Will be encrypted at rest and never returned in API responses.
        default_scopes:
          type: array
          items:
            type: string
        use_pkce:
          type: boolean
        revocation_endpoint:
          type: string
      required:
      - name
      - display_name
      - client_id
      additionalProperties: false
      description: Payload for creating an OAuth Provider. The client_secret is accepted as plaintext on create and stored encrypted.
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      additionalProperties: false
    OAuthProviderExchangePayload:
      type: object
      properties:
        code:
          type: string
        state:
          type: string
      required:
      - code
      - state
      additionalProperties: false
    OAuthProviderAuthStatus:
      type: object
      properties:
        oauth_provider_id:
          type: string
        oauth_provider_name:
          type: string
        authenticated:
          type: boolean
        expires_at:
          type: string
        scope:
          type: string
      required:
      - oauth_provider_id
      - oauth_provider_name
      - authenticated
      additionalProperties: false
      description: OAuth authentication status for a user against an OAuth Provider.
    OAuthProviderAuthorizeResponse:
      type: object
      properties:
        authorization_url:
          type: string
        state:
          type: string
        connected:
          type: boolean
      additionalProperties: false
      description: 'Response from the OAuth authorize endpoint. For authorization_code flow: contains authorization_url and state for browser redirect. For client_credentials flow: contains connected=true (token was fetched server-side, no redirect needed).'
    UpdateOAuthProviderPayload:
      type: object
      properties:
        name:
          type: string
        display_name:
          type: string
        grant_type:
          type: string
          enum:
          - authorization_code
          - client_credentials
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
          description: Optional client secret for confidential clients. Will be encrypted at rest and never returned in API responses.
        default_scopes:
          type: array
          items:
            type: string
        use_pkce:
          type: boolean
        revocation_endpoint:
          type: string
      additionalProperties: false
      description: Payload for updating an OAuth Provider. All fields are optional — only provided fields are updated. To clear the client_secret, set it to an empty string.
    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