Skip to Content
Service Accounts

Service Accounts

Service accounts are non-human Gestalt subjects for automation. Use them for release bots, scheduled workflows, shared service credentials, and other callers that should not run as a human user.

A service account is stored as a managed subject. Its canonical subject ID is:

service_account:<id>

Service accounts participate in the same authorization configuration and external credential systems as user subjects.

Setup Flow

  1. Declare the service-account subject in configuration where it is used.
  2. Grant users or groups permission to manage it.
  3. Grant app roles to the service account through authorization configuration.
  4. Connect upstream credentials for the service account through external credentials.
  5. Use the service account through runAs.

runAs

runAs is a host invocation delegation primitive. It tells Gestalt to execute a configured workflow or delegated tool call as another subject, usually a service account.

runAs changes the runtime principal and credential subject for that execution. It does not create the service account, grant app access, or create upstream credentials.

Config-managed workflow definitions support runAs:

workflows:
  definitions:
    nightly_sync:
      provider: local
      runAs:
        subject:
          id: service_account:nightly-sync
      steps:
        - id: list_issues
          app:
            name: github
            operation: issues.list
      on:
        nightly:
          schedule:
            cron: "0 3 * * *"
            timezone: America/New_York

When this activation fires, Gestalt invokes github.issues.list as service_account:nightly-sync. Subject-scoped connections resolve credentials stored for that same subject. Without runAs, config-managed workflows run as system:config and cannot use subject-scoped credentials.

Executable apps pass runAs per request through App.invoke options when they need to act as a service account. Agent tool calls and workflow steps keep their existing authority models and cannot override delegation with request runAs. This keeps delegated execution explicit and auditable.

  • Configuration explains subjects, resources, relations, and grants.
  • External Credentials explains where upstream credentials are stored and resolved.
  • Workflow explains schedules, triggers, and workflow execution identity.
  • Data Model describes the underlying managed-subject records.
ApplicationsSecurity