openapi: 3.0.3
info:
  title: Truto Admin 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
  - name: Link Tokens
    description: Generate tokens for customer-initiated account connections
  - name: MCP Servers
    description: Provision Model Context Protocol servers for AI agent access

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'

  /integrated-accounts/{id}/mcp:
    post:
      operationId: createMcpServer
      summary: Create MCP server for integrated account
      description: >-
        Provision a Model Context Protocol (MCP) server for an integrated account.
        Returns a secure tokenized URL that AI agents (Claude, ChatGPT, custom LLM
        frameworks) can use to invoke the integration's tools. The URL itself serves
        as the auth token. Optionally filter which methods are exposed or require
        additional API token authentication for enterprise security.
      tags:
        - MCP Servers
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Integrated account identifier.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMcpServerRequest'
      responses:
        '201':
          description: MCP server provisioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /link-tokens:
    post:
      operationId: createLinkToken
      summary: Create link token
      description: >-
        Generate a link token to initiate a Truto account connection flow from within
        your application. The link token is a short-lived credential passed to the
        Truto Link SDK or redirect URL to guide the end user through connecting their
        third-party account. At the end of the flow, an integrated account is created.
      tags:
        - Link Tokens
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLinkTokenRequest'
      responses:
        '201':
          description: Link token created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tenant Bearer token from the Truto dashboard.

  responses:
    Unauthorized:
      description: Authentication failed or token is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    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.

    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.

    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).

    CreateLinkTokenRequest:
      type: object
      required:
        - integration
      properties:
        integration:
          type: string
          description: Integration name for the connection flow (e.g., bamboohr, greenhouse).
        externalId:
          type: string
          description: Your internal identifier for the end user or organization initiating the connection.
        redirectUri:
          type: string
          format: uri
          description: URL to redirect the user to after completing the connection flow.
        scopes:
          type: array
          items:
            type: string
          description: Specific OAuth scopes to request, if applicable.
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata to attach to the integrated account on creation.

    LinkToken:
      type: object
      properties:
        token:
          type: string
          description: Short-lived link token for initiating the connection flow.
        linkUrl:
          type: string
          format: uri
          description: Full URL to redirect the user to for the connection flow.
        expiresAt:
          type: string
          format: date-time
          description: Expiration timestamp for the link token.

    CreateMcpServerRequest:
      type: object
      properties:
        allowedMethods:
          type: array
          items:
            type: string
          description: Limit the MCP server to only expose specific tool methods.
        requireAdditionalAuth:
          type: boolean
          description: Whether to require an additional API token for MCP server access.

    McpServer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the MCP server.
        mcpUrl:
          type: string
          format: uri
          description: Secure tokenized URL for connecting AI agents to this MCP server.
        transport:
          type: string
          enum:
            - http
            - stdio
          description: MCP transport protocol.
        integratedAccountId:
          type: string
          description: Identifier of the integrated account this MCP server is scoped to.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the MCP server was provisioned.

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error description.