Service users for workflows

Learn how Retool Workflows use service users to run scheduled, webhook-triggered, and query-triggered workflows with a defined set of permissions.

A service user is an identity that a workflow uses when a workflow is triggered from a schedule, webhook, or query. Each service user belongs to one permission group, so a workflow that runs as a service user has the same access as that group. You choose the group, and Retool creates and manages the service user for you.

This page explains why workflows need a run identity, how Retool picks the identity for each run, and what service users can and can't do. To assign one, refer to Run a workflow as a service user.

Why workflows need a run identity

Workflows often run without a person present. A schedule starts a run at midnight, a webhook receives a request from another system, or a query trigger starts a run when a message arrives from another system. None of these runs has a logged-in user whose permissions Retool can use to check access to resources.

Without a service user, Retool runs these workflows as an admin in your organization, and the workflow has admin-level access to every resource it uses. This also means features that evaluate permissions per identity, such as data access policies, have no identity to evaluate.

A service user replaces that implicit admin default with an identity you choose. Then, you can give the service user group access to only the resources the workflow needs.

How Retool picks the identity for a run

Retool resolves the identity when a run starts and uses it for the whole run.

How the run starts	Identity used
Schedule, webhook, or query trigger	The service user for the group selected in the workflow's Service user dropdown, if one is set. Otherwise, an admin in your organization.
Manual run from the workflow IDE, or a trigger from an app	The identity of the user who triggered the run, if your organization turned on the run workflow as the current user beta feature. Otherwise, an admin in your organization.

Service user access

A service user has the access of its permission group, and it has limits because it isn't a person.

What a service user can access

A service user can access what its group can access. Retool checks the group's permissions in two places:

• Workflow access: The group needs at least Use access to the workflow.
• Resource access: The group needs at least Use access to each resource the workflow queries. If it doesn't, the query fails.

If your organization uses data access policies, Retool also evaluates the policies for the group before the query runs. Data access policies can narrow what a service user reaches but can't grant access the group's permissions don't allow. Refer to Run workflows against enforced resources for details.

What a service user can't access

Some features that depend on a person's identity don't work for service user workflow runs:

• Service users can't sign in, use SSO, or hold multi-factor authentication.
• Service users can't use personal OAuth credentials. Resources that authenticate with each user's own OAuth credentials don't work for service user runs.
• Service users can't use human attributes in current_user. In a service user run, current_user has no email address. Refer to The Current User object.
• Service user runs can't run agent queries, such as queries with the RetoolAIQuery resource, query Retool Vectors, or dispatch a Retool Agent run.
• Service user runs can't query resources that use %USER_*% placeholders in their configuration.

A service user has a name based on its group, such as <group name> Service User, but no email address. It doesn't appear in your list of users, doesn't take a seat, and doesn't count toward your user total.

Who can change a run identity

Choosing a run identity is a privileged action. Retool limits it in the following ways:

• You can only choose a group that you belong to.
• A workflow has one run identity at a time.
• Once a workflow has a run identity, only members of the selected group and admins can edit the workflow.

Run history and audit logs

Run logs and block results for a service user run are visible only to people who can access the workflow and who share a group with the service user. This keeps data that a group can reach, but that the viewer can't, out of run history.

Service users don't have their own audit log events. Their actions appear under the following existing event types, with the service user as the actor instead of a person:

• RUN_WORKFLOW: A workflow run that executed as a service user. Blocked runs record a failure event.
• DATA_SECURITY_POLICY_QUERY_BLOCKED: A query from the run that a data security policy blocked.
• WORKFLOW_SECRETS_ACCESSED: Secrets Manager secrets the run read. Self-hosted only.
• UPDATE_WORKFLOW: A change to a workflow's run identity, recorded with a run_as change type.
• DELETE_GROUP: The deletion of a group, which names the retired service user.

An event identifies a service user by ID. The serviceUserId field holds the service user's UUID and userId is empty. The Audit Logs API, the retool_list_audit_logs MCP tool, and Datadog and Splunk streams all return the raw serviceUserId.

Source control

Run identities are included in a workflow's YAML file when you use source control. The file records the service user's ID and its group name. On deploy, Retool first tries to match the service user ID. If that ID doesn't exist, Retool matches the group name and finds or creates a service user for it. If no group with that name exists, the deploy fails.