Service accounts

A durable identity for a workload

A service account is a non-human Loam identity for a minisite, application, autonomous agent, scheduled job, or other workload that must keep working when an employee changes role or leaves the organization. The account belongs to one organization and one workspace. It has its own lifecycle, operation capabilities, current Engine grants, quotas, audit history, and replaceable child API keys.

"Agent", "minisite", and "automation" describe how an account is used. They are workload labels, not separate identity kinds. Use one service-account model so suspension, grants, audit, rotation, and offboarding behave the same way for every non-human workload.

In the Loam product, this area is called Service accounts & agents, and the durable record is described as a workspace identity. This guide uses the technical term service account because it documents the API and credential model.

Service account or user API key?

A service account is not a renamed user key and is not a fake user. It does not sign in through Supabase, receive an organization role, accept invitations, or count as a human seat.

Service-account IDs use the regional rw-us-east1-sa-... shape. The stable account states are active, suspended, and revoked. Revocation is terminal; suspension is the recoverable incident control.

Create one with the self-serve setup

Setup has three steps: Purpose and name, Data access, and Key and review. Choose the work and where it should happen; Loam selects the matching capabilities and access level. Open Advanced for capability overrides, exclusions, or a narrower key.

1. Open the workspace, then go to Settings > Service accounts & agents and choose Add service account.
2. In Purpose and name, choose the work and give it a name that describes the workload, such as CSV Viewer production. Keep the site and environment in the name or key label so audit records are immediately understandable.
3. Choose File analysis for a minisite that uploads visitor files and runs SQL over them. The selected work is Analyse uploaded files, creating visible private temporary analysis Namespaces. The identity automatically includes file_analysis plus query so an assigned human in use-as mode can work with its visible Namespaces and tables through the normal Loam UI.
4. In Data access, choose New datasetto create a dedicated location, or Existing datasetto choose one you already have. Editor access is selected automatically. Setup grants the service account Editor access only to that dataset. Alternatively, choose Entire workspaceto cover existing and future datasets. Viewer access alone cannot create analysis datasets. Under Advanced, you can choose Editor or Data admin on an existing dataset and add permission exceptions. Every analysis workspace is a visible private temporary Namespace; each CSV or Parquet import becomes an ordinary table, and multiple imports can be joined with SQL. Each Namespace shows its exact deletion time and can be extended within its lifetime cap. A human with the required permissions can keep it permanently or delete it. Ordinary durable workspace grants remain separately optional.
5. In Key and review, check the selected location, allowed work, and key expiry. Create a child key for one site and environment. Copy the one-time Worker secret JSON directly into that environment's secret store, then close the reveal screen. For a shared minisite bootstrap, open Advanced key options and keep only file_analysis plus query: child keys can only narrow the root. The shared bootstrap handler needs query to resolve and verify the configured parent ancestry before it creates a temporary Namespace. Engine grants restrict the key to that dedicated private parent subtree. The key and its machine JWT remain server-side; visitors receive a different reveal-once exact-Namespace token for direct import and query.

A query-only MCP agent receives Viewer access to its selected data.

{
  "apiToken": "loam_0123456789abcdef0123456789abcdef01234567",
  "workspaceId": "rw-us-east1-ws-0195a3c47d3e7ab18c4f123456789abc"
}

Treat the entire value as a server secret. Never put it in browser JavaScript, HTML, a public repository, a URL, analytics, logs, or an error response. The browser may receive short-lived signed upload capabilities during a file-analysis flow, but it never receives this long-lived child key or the regional machine JWT exchanged from it.

Human-only regional management API

Service accounts are workspace data-plane resources. Manage them on the exact regional origin selected by the workspace ID, using a current human Supabase bearer with permission-management authority:

GET|POST    /v1/workspaces/{workspacePublicId}/service-accounts
GET|PATCH|DELETE /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}
GET|POST    /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}/keys
DELETE      /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}/keys/{keyId}
GET|POST    /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}/use-bindings
DELETE      /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}/use-bindings/{granteePrincipalId}
GET|POST    /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}/permission-groups
DELETE      /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}/permission-groups/{groupPrincipalId}
POST        /v1/workspaces/{workspacePublicId}/service-accounts/{serviceAccountId}/assume

A service-account child key has a regional rw-us-east1-sak-... ID. Its plaintext appears only in the creation response; list and detail responses return metadata such as display prefix, lifecycle, expiry, and last use, never the secret or its hash. Machine and assumed-service tokens are rejected on every management route regardless of their data grants.

Capabilities and data grants are separate

Authorization has two independent questions:

• Operation capabilities say what class of work the account may attempt: query, namespace_ingest, file_analysis, or mcp.
• Engine grants say which workspace resources the account may view, edit, or administer. Explicit denies still win.

Effective authority is the live intersection of the child key's optional narrowing, the service account's current capabilities, its current resource grants, and the organization's current entitlement. A child key can narrow the account, but it can never broaden it. A JWT carries identity and purpose, not a permission snapshot, so suspending the account, revoking the key, changing a grant, or removing a capability takes effect on the next request even for an already-issued JWT.

file_analysis is the single analysis capability. With a current Editor or Admin grant on an allowed parent Namespace or Workspace Root, it may create ordinary private temporary Namespaces and issue reveal-once analysis tokens. Each token is confined to one exact Namespace and may import files, query its normal tables with one SELECT, extend within the lifetime cap, or delete that temporary Namespace. It does not imply unrestricted query, general namespace_ingest, durable namespace_create, retention through namespace_lifecycle, or mcp. The File analysis preset adds query to the root for assigned humans using the normal Namespace and table UI. A shared minisite bootstrap child key also keeps query because the handler must resolve and verify its configured parent ancestry. Its query capability remains effective inside the granted subtree. The key remains bounded by Engine grants to the dedicated private parent subtree and is never exposed to the browser. Exact-Namespace SELECT by a visitor is authorized through the issued analysis token, not through the bootstrap child key.

Root-level analysis creation uses an explicit parentId: null. A dedicated dataset keeps the account's access limited to that subtree. The Upload data capability imports into existing datasets; it does not authorize the service account to create durable datasets.

Agents receive their direct grants plus grants from groups to which the Agent was explicitly added. They never inherit Everyone or the acting human's groups, so ambient human access cannot silently widen the workload.

Service-account Admin access applies only to data resources. A machine credential cannot create or administer service accounts, keys, grants, organization membership, billing, or human sessions.

Namespace leases are separate catalog state

File analysis creates an ordinary Namespace that inherits current parent grants without adding an ownership grant. Its temporary lifetime and initiating service account live in a separate Namespace lease, not in the Namespace node. The lease is lifecycle attribution, not an authorization bypass. Additional humans or service accounts see the Namespace only through explicit current Engine grants.

Key rotation, suspension, and revocation preserve the data. Retaining an analysis Namespace removes its lease and scoped tokens while preserving the same ordinary nodes and grants. Expired lease cleanup uses narrow regional lifecycle authority and the ordinary Namespace deletion path, so it remains safe and available when the initiating account is inactive.

Use one child key per site and environment

Child keys are replaceable credentials for one root account. Production, preview, staging, and different minisites each get a different key. That gives every deployment independent revocation, expiry, attribution, and rotation without duplicating Namespaces or grants.

Keys under one account still share the account's identity, resources, and plan-governed quotas. Creating or rotating a key does not reset storage, upload, analysis, or query usage. For anonymous visitors who share one minisite key, each analysis workspace receives a distinct reveal-once token bound to its exact temporary Namespace. A stable Namespace node public ID grants nothing, so one visitor's token cannot access another visitor's Namespace, import, table, or ingestion run.

For a general workload, a new key can use Same data access as workspace identity. A shared minisite bootstrap key keeps only file_analysis plus query. Open Advanced to restrict it to the dedicated private parent subtree used for temporary Namespace creation. Restricted rules intersect the account's current grants; an empty restricted selection means no resource operations. The query capability does not grant access outside those current Engine grants.

Rotate without downtime

On the account detail page, choose Create replacement key, then use the guided overlap:

1. Create a replacement child key with the same or narrower scope.
2. Copy its secret once and deploy it to the intended environment.
3. Verify exchange and a harmless health operation with the new key.
4. Choose Revoke old key after the deployment overlap ends.

Revoking one child key leaves the account and sibling keys active. Suspending the account blocks every child key and any human use-as session. Deleting or offboarding the person who created the account does not delete the workload, its keys, or data it can access.

Use this workspace identity

An authorized human can open a service account and choose Use this workspace identity to test exactly what the workload can see and do. Loam issues a 15-minute, purpose-bound assumption token and shows a persistent Working as <name> banner with an explicit Return to my account action.

This is not a second login and it does not reveal or reuse a child key. Data requests use exactly the service account's authority, never the union of human and service-account permissions and never a fallback to the human's broader access. Account and key management remain human-authenticated while the acting data client is separate and memory-only. Loam clears acting data caches when entering or leaving the mode and exits on token expiry, authentication failure, sign-out, or a workspace change.

A human needs a direct Agent-use binding or current membership in a group with a use binding. Loam rechecks both the human actor and the effective Agent on every request, rejects nested or machine-initiated assumption, and records both identities in the audit trail. A use binding grants no data permission and does not add the Agent to a permission group.

The workspace selector presents this as Data identity, with My account and eligible active Agents as options. Losing the direct or group binding exits use-as just like expiry, a 401, sign-out, or changing workspace.

Operational checklist

• Use a descriptive service-account name and child-key label.
• Give each site and environment a distinct child key.
• Set key and account expiry where the workload has a known end date.
• Start with the narrowest operation capability and no resource grants beyond the selected analysis Namespaces.
• Test permissions with the short-lived use-as mode.
• Rotate keys regularly and revoke replaced or unused keys.
• Suspend the whole account when a workload is compromised or no longer needed; do not delete customer data as an incidental revocation step.
• Review audit events by human actor, service-account ID, and child-key ID. Secret material, SQL, filenames, and file contents are never audit fields.

Next: upload files and analyse them with SQL

Continue with the file analysis guide to create a private temporary Namespace, import multiple files through standard signed ingestion, join their ordinary tables, and extend, delete, or keep the Namespace permanently.