Skip to main content
A service account is a non-human member of an organization. Automations can run as a service account instead of as the person who created them. Owners and Admins create and manage service accounts.
Service accounts are in beta. A Super Admin turns them on for the installation. See Turn On Service Accounts.

​
When to Use a Service Account

By default, an automation runs as the person who created it, with that person’s connected Git accounts, secrets, and budget. Use a service account when the automation belongs to the team rather than to one person:
  • Keep automations running when people leave. When a person is removed from the organization, the automations that run as them stop. An automation that runs as a service account keeps running.
  • Use shared, dedicated credentials. Give the service account its own secrets, such as a bot token with only the access the automation needs, instead of relying on a person’s tokens.
  • Control who changes it. Only Owners and Admins can edit, run, turn on, or delete an automation that runs as a service account. Members can view it, but can’t change it, even if they created it.
  • Track and limit spend separately. A service account can have its own monthly budget, and its runs are not billed to a person.
  • Stop a group of automations at once. Disable the service account to stop every automation that runs as it, for example after a credential leak.
Service accounts do not take a license seat, can’t sign in, and don’t appear in the organization’s member list.

​
Turn On Service Accounts

A Super Admin turns on Enable Service Accounts (beta) on the Instance Settings page of the Super Admin dashboard. The change takes effect without a redeploy.

​
Create a Service Account

  1. Go to Settings > Service Accounts.
  2. Click Create service account.
  3. Enter a name, such as nightly-report. Each name must be unique in the organization.
A service account belongs to one organization. Deleting the organization deletes its service accounts.

​
Give a Service Account Credentials

A service account has no connected Git accounts. A run that uses it gets:
  • The service account’s own secrets.
  • The organization’s shared secrets.
  • The organization’s LLM settings.
To add a secret, click Secrets and budget next to the service account, then click Add secret. For example, add a GITHUB_TOKEN secret with a bot token so the automation can work with your repositories. Secret values are write-only. You can replace or delete a value, but you can’t view it after you save it. OPENHANDS_API_KEY is reserved, because OpenHands adds it to every run.

​
Set a Budget

When your installation uses the LiteLLM gateway, Secrets and budget also shows a Monthly budget section. Enter a monthly limit in dollars to cap the service account’s spend. Without a limit, the organization default applies. Click Remove limit to go back to the default.

​
Run an Automation as a Service Account

You must be an Owner or Admin.
  • New automation: In the automation setup, choose the service account in the Runs as field. The default is Me.
  • Existing automation: Open the automation and choose Change runs as. Pick a service account, or Me to run it as yourself.
When you change who an automation runs as:
  • OpenHands turns the automation off. Turn it on again after you check that the new identity has the secrets the automation needs. Credentials do not move with the automation.
  • The automation keeps its run history and stored data.
  • You can’t change a draft, or an automation with a pending or running run.
The automation’s detail page shows Automation Runs As with the service account name and an SA badge, and Created by with the person who created it. Members see Service account instead of the name. An automation that runs as a service account uses plugins at a fixed commit. A push to the plugin’s repository does not change what the automation runs.

​
Manage Service Accounts

On Settings > Service Accounts, use the buttons next to a service account to:
  • Rename it.
  • Disable it. This revokes its keys, and its automation runs fail until you enable it again. The list shows a Disabled label.
  • Enable it again.
  • Delete it. You can’t undo this. OpenHands refuses to delete a service account while any automation runs as it. Change who those automations run as, or delete them, first.
A service account can’t create automations, change who an automation runs as, or manage the automation it runs.

​
Next Steps