Arkova Integrations API

openapi: 3.2.0
info:
  title: Arkova Verification Integrations API
  version: 1.0.1
  description: Programmatic credential verification API. Verify credentials anchored on the Bitcoin network. Worker-generated v1 JSON errors expose common top-level code and message fields. The legacy error field is retained unchanged (string or object), along with details and quota context, for existing integrations. Parse code and message for new integrations. Upstream gateway errors may not be JSON. Revision 1.0.1 restores legacy label and DIPLOMA inputs and clarifies receipts and webhook payloads; the endpoint version remains v1.
  contact:
    name: Arkova Support
    url: https://arkova.ai
servers:
- url: /api/v1
  description: Verification API v1
security:
- ApiKeyBearer: []
- ApiKeyHeader: []
tags:
- name: Integrations
  description: Third-party connector metadata endpoints (Google Drive, DocuSign) — session-authenticated, not reachable with an API key
paths:
  /integrations/google_drive/folders:
    get:
      summary: List a Google Drive folder's child folders
      description: 'Connectors page folder picker (My Drive only — shared drives are not supported). Session-authenticated (Supabase JWT), org-admin only; NOT reachable with an API key. Metadata-only: never returns file content. `hasChildren` is always `null` (unknown) — Drive has no cheap "has subfolders" signal, so every folder renders as expandable.'
      operationId: listGoogleDriveFolders
      tags:
      - Integrations
      security:
      - SupabaseJWT: []
      parameters:
      - name: org_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: parent
        in: query
        schema:
          type: string
          default: root
        description: Drive folder id to list, or the literal "root" for My Drive.
      - name: page_token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Child folders of the requested parent
          content:
            application/json:
              schema:
                type: object
                properties:
                  folders:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        hasChildren:
                          type:
                          - boolean
                          - 'null'
                          description: Always null in v1 — unknown.
                        driveId:
                          type:
                          - string
                          - 'null'
                          description: Always null in v1 — My Drive only.
                  nextPageToken:
                    type: string
                    description: Omitted when there is no further page.
        '400':
          description: '`drive=` (shared drive) query param is not supported in v1, or the query failed validation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Google Drive is not connected for this organization (`not_connected`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: The stored OAuth grant cannot list folders (`insufficient_drive_scope`) or the connection needs to be re-authorized (`reconnect_required`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Google Drive is unavailable (`drive_unavailable`) — may carry `Retry-After`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry is allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
            properties:
              code:
                type: string
              message:
                type: string
        code:
          type: string
          description: Common machine-readable error code; legacy error remains unchanged.
        message:
          type: string
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: 'API key as Bearer token: `Authorization: Bearer ak_live_...`'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key via header: `X-API-Key: ak_live_...`'
    SupabaseJWT:
      type: http
      scheme: bearer
      description: Supabase JWT for key management endpoints