openapi: 3.0.3
info:
  title: Truto Admin Accounts Integrated Accounts API
  description: The Truto Admin API enables programmatic management of the Truto integration platform, including managing integrated accounts, generating link tokens for customer OAuth flows, running post-install actions, and provisioning MCP servers for AI agent access.
  version: 1.0.0
  contact:
    url: https://truto.one/docs/api-reference/admin
servers:
- url: https://api.truto.one
  description: Truto API
security:
- bearerAuth: []
tags:
- name: Integrated Accounts
  description: Manage connected third-party accounts
paths:
  /integrated-accounts:
    get:
      operationId: listIntegratedAccounts
      summary: List integrated accounts
      description: List all integrated accounts in the tenant. Integrated accounts represent connections between your Truto tenant and a customer's connected third-party app.
      tags:
      - Integrated Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: integration
        in: query
        description: Filter by integration name (e.g., bamboohr, greenhouse, salesforce).
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter by account status.
        required: false
        schema:
          type: string
          enum:
          - active
          - inactive
          - error
      - name: page
        in: query
        description: Page number for pagination.
        required: false
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        description: Number of results per page.
        required: false
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: List of integrated accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegratedAccountListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createIntegratedAccount
      summary: Create integrated account
      description: Programmatically create an integrated account. Typically used when you already have credentials (e.g., API keys) for the integration and want to register them directly without a link token flow.
      tags:
      - Integrated Accounts
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegratedAccountRequest'
      responses:
        '201':
          description: Integrated account created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegratedAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /integrated-accounts/{id}:
    get:
      operationId: getIntegratedAccount
      summary: Get integrated account
      description: Retrieve a single integrated account by ID.
      tags:
      - Integrated Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Integrated account identifier.
        schema:
          type: string
      responses:
        '200':
          description: Integrated account details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegratedAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteIntegratedAccount
      summary: Delete integrated account
      description: Delete an integrated account and revoke all associated credentials.
      tags:
      - Integrated Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Integrated account identifier.
        schema:
          type: string
      responses:
        '204':
          description: Integrated account deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /integrated-accounts/{id}/run-post-install-actions:
    post:
      operationId: runPostInstallActions
      summary: Run post-install actions
      description: Manually run post-install actions for an integrated account. Post-install actions are configured per integration and typically fetch metadata from the underlying API to store in the integrated account context (e.g., tenant ID, region, base URL). These run automatically on connection but can be re-run manually if needed.
      tags:
      - Integrated Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Integrated account identifier.
        schema:
          type: string
      responses:
        '200':
          description: Post-install actions completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegratedAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    CreateIntegratedAccountRequest:
      type: object
      required:
      - integration
      properties:
        integration:
          type: string
          description: Integration name (e.g., bamboohr, salesforce).
        name:
          type: string
          description: Display name for this integrated account.
        credentials:
          type: object
          additionalProperties: true
          description: Authentication credentials for the integration (e.g., api_key, access_token).
    IntegratedAccountListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/IntegratedAccount'
        total:
          type: integer
          description: Total number of integrated accounts.
        page:
          type: integer
          description: Current page number.
        limit:
          type: integer
          description: Results per page.
    IntegratedAccount:
      type: object
      description: An integrated account representing a connection to a customer's third-party app.
      properties:
        id:
          type: string
          description: Unique identifier for the integrated account.
        integration:
          type: string
          description: Integration name (e.g., bamboohr, greenhouse, salesforce).
        status:
          type: string
          enum:
          - active
          - inactive
          - error
          description: Connection status of the integrated account.
        name:
          type: string
          description: Display name for this integrated account.
        context:
          type: object
          additionalProperties: true
          description: Metadata stored from post-install actions (e.g., tenant ID, region).
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the account was connected.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the account was last updated.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error description.
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed or token is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tenant Bearer token from the Truto dashboard.