Service accounts

A service account is a non-human identity that belongs to a workspace. It exists to hold API keys for automation (a CI/CD pipeline, a script, a scheduled job) so that automation authenticates as the workspace's own robot rather than as a person.

The difference from a personal access token matters:

	Personal access token	Service account key
Acts as	You, the person	The service account (a machine identity)
Survives	Until you're offboarded	Independent of any person
Managed by	The owning user	Workspace admins
Best for	Your own scripts / the CLI on your laptop	CI/CD and unattended automation

If a pipeline authenticates with a person's token, the pipeline breaks the day that person leaves. A service account doesn't, which is why it's the recommended credential for CI/CD.

How it works

• A service account is scoped to one workspace and has a single workspace role (owner / admin / member / guest), set when it's created. Its keys can never do more than that role allows.
• It owns one or more API keys. Each key carries its own scopes and optional expiry, and is shown once at creation.
• The service account does not appear in the members list and cannot log in to the dashboard; it only acts through its keys against the API.

Binding to a project

A service account can optionally be bound to one project. A bound account's keys act only on that project's repositories, triggers, builds, variables, and deployments, whatever its role and scopes.

Anything that belongs to the whole workspace is refused with 403, because there is no project for the binding to match. This covers repo hosts (SCM connections), members and invitations, workspace settings, usage reports and insights, the audit log, container registries, and Loha Repos setup. Use an unbound service account for automation that manages the workspace itself.

Managing service accounts

Find them under Workspace → Settings → Service accounts. You need the admin role (or higher) to create, disable, or mint/revoke keys; any member can view the list.

• Create: give it a name, an optional description, and a role. You can only grant a role you're allowed to assign (an admin can't create an owner service account).
• Mint a key: pick the scopes the automation needs and an optional expiry. Copy the key immediately; it isn't shown again. Store it in your CI secret store.
• Revoke a key: stops that one key from authenticating, immediately and permanently.
• Disable the account: immediately neutralizes all of its keys at once. Use this if you suspect compromise or are retiring the automation. The account and its key records are kept (for the audit trail); re-enabling is a future capability.

The Last used column shows when one of the account's keys most recently authenticated, so you can spot keys that are no longer in use.

Using a key

A service account key is used exactly like any API token: send it as Authorization: Bearer loha_… or the x-api-key header. The two common paths:

• The Loha CLI: set the key as the LOHA_TOKEN environment variable. See Using the CLI in CI/CD.
• Direct API calls: see the API reference.

Attaching to a trigger

A service account can also back a trigger. When a webhook or scheduled trigger has a service account assigned, its automatic runs are attributed to the service account instead of being left anonymous, so the audit log shows who (well, what) deployed, even when the cause was a push rather than a person.

If the trigger also has token injection enabled, every run gets a short-lived credential as the LOHA_TOKEN environment variable, available to the build's steps for calling the API. That injected token is:

• ephemeral: it expires shortly after the run and is revoked when the run finishes;
• bound to the run: it can't be reused by anything else;
• never wider than the account: its scopes are clamped to the service account's scopes (it defaults to read-only).

See Using the CLI in CI/CD for the related pattern of putting a service account key in LOHA_TOKEN yourself.

Auditing

Every action a service account takes is recorded in the audit log, attributed to the service account by name, so "who deployed this?" has a real answer even when the actor is a machine. Creating, disabling, and minting/revoking keys are audited too, attributed to the admin who performed them.