hyreflow-ai Integrations API

openapi: 3.2.0
info:
  title: hyreflow engine (local) Integrations API
  version: 0.1.0
tags:
- name: Integrations
paths:
  /api/v2/integrations/{provider}/oauth/credentials:
    put:
      summary: Integration Oauth Save Credentials
      description: 'Save the workspace''s OWN OAuth app credentials for `provider`, registered by the workspace directly

        with the vendor. The OVERRIDE path: connecting normally runs on Hyreflow''s managed app and needs none

        of this (see integration_oauth.py''s module docstring), so this is for a workspace that wants its own

        audit trail / rate-limit bucket. Overwrites any prior connection outright, including a live

        refresh_token — see `save_credentials`.'
      operationId: integration_oauth_save_credentials_api_v2_integrations__provider__oauth_credentials_put
      security:
      - HTTPBearer: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Integrations
  /api/v2/integrations/{provider}/oauth/start:
    get:
      summary: Integration Oauth Start
      description: 'Kick off a workspace''s CRM/ATS connect: mint a single-use state bound to this workspace + provider

        and return the vendor''s consent-screen URL for the browser to navigate to (JSON, not a redirect — the

        caller is the web BFF''s server-side fetch, not the browser itself; see infra/dokploy/web.tf''s

        `web_code_paths` note on why this can''t just be a raw 302 from a plain ``). 404 when the

        provider has no OAuth config; 400 only when there is no app to connect WITH at all — neither a

        Hyreflow-owned managed app in env nor credentials the workspace pasted itself.


        The state is ALSO mirrored into a short-lived httponly cookie, scoped to the callback path. The

        workspace/provider binding on the state row alone proves who requested the connect, not which

        BROWSER is completing it — without the cookie, an attacker could mint a state for their own

        workspace via their own bearer token, then hand the resulting consent URL to a victim; the victim''s

        JobAdder login would land the victim''s tokens in the attacker''s workspace (a login-CSRF /

        state-injection variant on the OAuth dance). The callback below requires the cookie to match the

        state it''s given, which only the browser that actually started THIS flow will have.'
      operationId: integration_oauth_start_api_v2_integrations__provider__oauth_start_get
      security:
      - HTTPBearer: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Integrations
  /api/v2/integrations/{provider}/oauth/callback:
    get:
      summary: Integration Oauth Callback
      description: 'The vendor redirects here. Verify our state (row AND the matching cookie set by /start — see its

        docstring), exchange the code for tokens against the SAME app /start sent them to (the workspace''s own

        pasted credentials if it has them, else Hyreflow''s managed app — `app_credentials`), and store the

        result as the workspace''s connected credential for `provider`. Any failure bounces to the dashboard''s

        integrations page with an error flag -- this is a redirect surface, never a JSON error.'
      operationId: integration_oauth_callback_api_v2_integrations__provider__oauth_callback_get
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: state
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: State
      - name: code
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Code
      - name: error
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Integrations
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer