openapi: 3.2.0
info:
  title: Pipeshub Service Accounts API
  version: 1.0.0
  contact:
    name: API Support
    email: support@pipeshub.com
  description: 'Operations tagged Service Accounts across 2 of this provider''s published API definitions: pipeshub-openapi.yaml, pipeshub-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{instance_url}/api/v1'
  description: Base API URL
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL (without /api/v1)
- url: '{instance_url}'
  description: Root URL (used for MCP endpoints mounted at /mcp)
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Service Accounts
  description: 'Machine identities that automation authenticates as, so a script reads with

    its own permissions rather than borrowing a person''s.'
paths:
  /service-accounts:
    get:
      tags:
      - Service Accounts
      summary: List service accounts
      description: 'Every service account in the caller''s organisation, newest first.


        The organisation comes from the caller''s own token, never from the

        request, so an administrator of one organisation cannot reach another''s.'
      operationId: listServiceAccounts
      security:
      - bearerAuth: []
      - oauth2:
        - user:read
      responses:
        '200':
          description: Service accounts in this organisation
          content:
            application/json:
              schema:
                type: object
                properties:
                  serviceAccounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceAccount'
        '400':
          description: Admin access required
        '401':
          description: Not authenticated
        '403':
          description: Token lacks the required scope
    post:
      tags:
      - Service Accounts
      summary: Create a service account
      description: 'Creates a machine identity and publishes the same `userAdded` event

        that creating a person publishes, so the permission graph builds its

        node, its edge to the organisation, its knowledge base and its

        membership of the organisation''s "All" team.


        The account is always a member and never an administrator, whoever

        creates it. It cannot sign in.


        Reusing the name of a previously deleted service account restores that

        record rather than failing: the address is uniquely indexed and the

        graph node is keyed by it, so a second record would leave the name

        permanently unusable. Every field is reset from this request, and the

        account comes back enabled.'
      operationId: createServiceAccount
      security:
      - bearerAuth: []
      - oauth2:
        - user:invite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAccountCreateRequest'
      responses:
        '201':
          description: Service account created, or a deleted one of the same name restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
        '400':
          description: Invalid name, or admin access required
        '401':
          description: Not authenticated
        '403':
          description: Token lacks the required scope
        '409':
          description: A service account of that name already exists
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /service-accounts/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        pattern: ^[0-9a-fA-F]{24}$
      description: Mongo id of the service account
    get:
      tags:
      - Service Accounts
      summary: Get a service account
      description: '`kind` is part of the lookup rather than checked afterwards, so a

        colleague''s user id passed here returns 404 rather than their record.'
      operationId: getServiceAccount
      security:
      - bearerAuth: []
      - oauth2:
        - user:read
      responses:
        '200':
          description: The service account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
        '400':
          description: Admin access required
        '401':
          description: Not authenticated
        '403':
          description: Token lacks the required scope
        '404':
          description: No such service account in this organisation
    patch:
      tags:
      - Service Accounts
      summary: Rename, describe, disable or re-enable a service account
      description: 'Disabling stops tokens that have already been issued, not only the next

        sign-in. Renaming is passed on to the permission graph, which keeps its

        own copy of the display name; disabling is not, because the graph does

        not need it.'
      operationId: updateServiceAccount
      security:
      - bearerAuth: []
      - oauth2:
        - user:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAccountUpdateRequest'
      responses:
        '200':
          description: The updated service account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
        '400':
          description: Empty body, invalid field, or admin access required
        '401':
          description: Not authenticated
        '403':
          description: Token lacks the required scope
        '404':
          description: No such service account in this organisation
    delete:
      tags:
      - Service Accounts
      summary: Delete a service account
      description: 'Marks the record deleted, removes it from every group and tells the

        permission graph, which marks its node inactive. The name can be used

        again, which restores this record rather than creating a second one.'
      operationId: deleteServiceAccount
      security:
      - bearerAuth: []
      - oauth2:
        - user:delete
      responses:
        '204':
          description: Deleted
        '400':
          description: Admin access required
        '401':
          description: Not authenticated
        '403':
          description: Token lacks the required scope
        '404':
          description: No such service account in this organisation
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
components:
  schemas:
    ServiceAccountUpdateRequest:
      type: object
      additionalProperties: false
      description: 'Request body for `PATCH /service-accounts/{id}`. At least one field is

        required; an empty body is refused rather than silently doing nothing.

        '
      minProperties: 1
      properties:
        fullName:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
        isDisabled:
          type: boolean
    ServiceAccount:
      type: object
      additionalProperties: false
      description: A machine identity in this organisation.
      required:
      - id
      - slug
      - fullName
      - email
      - isDisabled
      properties:
        id:
          type: string
          description: Mongo id of the underlying user record
          example: 507f1f77bcf86cd799439012
        slug:
          type: string
          description: Short name, unique within the organisation
          example: nightly-sync
        fullName:
          type: string
          description: Display name, shown wherever a user is shown
          example: Nightly sync
        email:
          type: string
          description: 'Reserved address under `service.pipeshub.internal`, derived from the

            slug. Not a mailbox: the domain is reserved by RFC 8375 and never

            resolves. It exists because the user record requires an address and

            the permission-graph sync looks users up by it.

            '
          example: svc-nightly-sync-507f1f77bcf86cd799439011@service.pipeshub.internal
        description:
          type: string
          description: What this account is for
        isDisabled:
          type: boolean
          description: 'When true, tokens already issued stop working as well as new

            sign-ins being refused. The record, its group memberships and its

            permission-graph node all survive, so it can be switched back on.

            '
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServiceAccountCreateRequest:
      type: object
      additionalProperties: false
      description: Request body for `POST /service-accounts`. Validated by `createServiceAccountSchema` (Zod).
      required:
      - slug
      - fullName
      properties:
        slug:
          type: string
          minLength: 3
          maxLength: 48
          pattern: ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$
          description: 'Letters, digits and single hyphens, not starting or ending with

            one. Becomes the local part of the account''s address, which is

            lowercase — mixed case is accepted here and lowercased rather than

            refused, which is why the pattern allows it.

            '
          example: nightly-sync
        fullName:
          type: string
          minLength: 1
          maxLength: 100
          example: Nightly sync
        description:
          type: string
          maxLength: 500
          example: Reads the handbook for the release digest
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token for authenticated requests.


        A personal access token (see the **Personal Access Tokens** tag) is a

        `phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.

        The prefix is display-only, added for secret-scanner detectability; the

        gateway strips it before verifying the token, so send it exactly as

        issued, prefix included.

        '
    scopedToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Scoped JWT token for service-to-service authentication.

        Format: "Bearer {scoped_token}"

        Required scopes vary by endpoint.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 authentication with fine-grained scopes.

        Supports authorization_code (with PKCE) and client_credentials flows.

        OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.

        For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the OAuth app creator — see **OAuth Provider** tag.

        '
      flows:
        authorizationCode:
          authorizationUrl: /api/v1/oauth2/authorize
          tokenUrl: /api/v1/oauth2/token
          refreshUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:read: Read semantic search results and history
            semantic:write: Execute semantic search
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            crawl:delete: Delete crawling jobs
        clientCredentials:
          tokenUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:write: Execute semantic search
            semantic:read: Read semantic search results and history
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
x-refined-from:
- pipeshub-openapi.yaml
- pipeshub-openapi.yml