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 and external credential systems as user subjects.

Setup Flow

  1. Create the managed subject through the managed subjects API.
  2. Grant users or groups permission to manage it.
  3. Grant app roles to the service account through authorization.
  4. Connect upstream credentials for the service account through external credentials.
  5. Use the service account through a subject-owned API token or runAs.

CLI Setup

Use a subject-owned API token when automation calls Gestalt over HTTP, CLI, or MCP as the service account. The token owner is the service account subject, so normal app authorization and credential lookup use that subject.

gestalt authorization subjects create release-bot \
  --display-name "Release Bot"
 
gestalt authorization subjects grants set service_account:release-bot github \
  --role viewer
 
gestalt authorization subjects integrations connect service_account:release-bot github
 
gestalt authorization subjects tokens create service_account:release-bot \
  --name release-bot

The plaintext token is returned once. Store it like any other secret.

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 schedules and event triggers support runAs:

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

When this schedule 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 and agent tool calls may also use runAs only when the caller has declared that delegation in configuration. This keeps delegated execution explicit and auditable.

  • Authorization explains subjects, resources, relations, and grants.
  • External Credentials explains where upstream credentials are stored and resolved.
  • Workflow explains schedules, triggers, and workflow execution identity.
  • HTTP API lists the managed subject, credential, grant, and token routes.
  • Data Model describes the underlying managed-subject records.
ApplicationsSecurity