Service Accounts

Service Accounts are non-human principals. Use them whenever RevoEngine or an external system must act without an interactive person: scheduled Jobs, CI/CD, server integrations, durable Agents, and API clients.

Create a workload identity

Open Service Accounts, select Add, and configure:

Field	Required	Purpose
Name	Yes	Unique workload name; the UI validates the service-account naming pattern.
Restricted access	No	Restricts management to explicitly admitted users and Groups. The default admits the creator and the new Service Account itself.
Access users and Groups	No	Principals allowed to manage the account, subject to their IAM roles.
Groups and Permission groups	No	Execution memberships saved atomically with the account.
Metadata	No	Environment, system, cost centre, rotation owner, or other organization data.
Advanced metadata	No	Instance-specific advanced attributes; manage under your identity policy.

The platform creates the account email/identifier; it is displayed as read-only after creation. The editors use metadata and metadataAdvanced, each limited independently to 16 KiB of UTF-8 JSON and 64 top-level keys. See Account metadata for Platform API compatibility and low-code access. The identity, management ACL, and execution memberships are saved together. Membership changes remain drafts until Save. Open a saved account to manage API keys. Access controls who may manage the Service Account. Groups and Permission groups control what the Service Account may execute or access. Adding a Group to one section does not add it to the other. Public management access admits any eligible caller with the required IAM role; restricted access admits only listed users and members of listed Groups. Creator and self access are explicit default ACL entries and can be removed.

Built-in System account

System is a protected, active Service Account with instance-administrator permissions. It is separate from a human Support session and can be selected as an execution account or a resource owner. Its identity, permissions, memberships, lifecycle, and API keys cannot be edited through ordinary account-management actions. The Platform API Accounts list and detail identify System by its fixed userId: "00000000-0000-0000-0000-000000000000" and serviceAccount: true. Limited field projections retain its service-account type. The account is provisioned automatically; callers do not create it manually. System appears as a real account in Service Accounts and account selectors. Public clients use its account ID and serviceAccount type, with the same public account shape as other Service Accounts. Select System deliberately for work that needs instance-wide authority. For Endpoint defaults, use Settings → Endpoints; individual Endpoints and Job Templates can choose their own account. Configured execution as an administrator Service Account requires approved Component and library code. Ordinary Service Accounts retain their existing lifecycle and least-privilege memberships.

Ownership and management access

An ordinary Service Account can own a Group or another resource that supports an account owner, just like System. For Groups, the Platform API uses ownerType: "USER" and the owning account’s userId; GROUP remains available for a Group owner. A Service Account’s own Access policy is its management ACL. A portable CLI owner is translated into that ACL; it does not add execution memberships or resource access. Resource ownership, account-management access, and execution permissions remain separate decisions.

Design one account per trust boundary

Do not share one service account across unrelated systems. Separate identities let you rotate or disable one integration without stopping every workload.

svc-checkout-prod       -> Endpoint invocation and Orders access
svc-settlement-worker   -> settlement Job and restricted finance Tables
svc-ci-release          -> Component release permissions only

Use metadata such as environment, system, ownerTeam, and rotationPolicy for discovery. Never store the key value itself in metadata.

Grant access

Add the account to a Permission group containing only the required platform roles.
Add it to Groups used by restricted Tables, Views, or Storage folders.
Test the exact API or automation operation.
Remove any temporary administrative access used during setup.

The account executing a Job or integration is re-evaluated at runtime. A template created by an administrator does not inherit administrator access. A caller can delegate only Permission groups they currently personally belong to, even with USER_ADMIN; INSTANCE_ADMIN is the exception. This ceiling also applies when issuing or rotating the account’s keys and binding it as an execution principal.

API keys

Open a saved Service Account and select API Keys. Create a key for one client or deployment, store the value once in a secret manager, and record its owner and rotation date.

curl "$REVO_PLATFORM_URL/api/v1/automation/job" \
  -H "Authorization: Bearer $REVO_API_KEY"

Keys inherit the account’s current status, platform roles, Permission groups, and resource ACLs. Disabling the account invalidates admission without requiring every key row to be deleted first. List, get, and update return key metadata without a usable credential. Create and rotate reveal the new credential exactly once.

Never paste a key into Component source, metadata, Job input, Chat, Assistant, screenshots, or documentation. Resolve it from an approved secret manager or RevoEngine Secrets.

Expiry reminders and direct key links

In Settings → Preferences → Notifications → API key expiry, System messages and email are enabled by default for each human user in the workspace. The first reminder defaults to 7 days; choose a whole number from 2 to 365. A second reminder is always due 24 hours before expiry, followed by an expired notice. Each channel can be disabled independently. Emails use the workspace notification layout and include an Open API key action plus a preferences link. Personal-key reminders go to the authorized owner. Service-account reminders go to currently authorized human key managers, respecting account hierarchy and restricted account access. Notification links open the specific key after sign-in and enforce current access; the link never contains the credential. The deadline is an absolute UTC instant. Queue retries can delay receipt. Revoked keys do not receive later reminders; rotation invalidates the old deadline and plans notices for the predecessor’s grace cutoff and the replacement’s expiry. An old-key notice asks you to verify that the integration uses its replacement. Keys without an expiry have no expiry notifications. Adoption and preference changes schedule future reminders without replaying historical ones. Additional automation event (days) is optional (1–365 days). It publishes ACCOUNT_API_KEY_EXPIRING without another email or System message. Native events continue when notification channels are disabled; equal deadlines are combined. Use Events and filter by reminderDays to react at a particular offset.

Lifecycle and roles

The UI supports save, API-key management, activate, disable, enable/disable platform access, delete, and restore.

Action	Role
List, inspect, and open API Keys	`USER_READ`, `USER_WRITE`, or `USER_ADMIN`, plus management access
Create, edit, activate, disable, change platform access, delete, restore, or mutate keys	`USER_WRITE` or `USER_ADMIN`, plus management access
Assign execution Group memberships	`USER_ADMIN` or `INSTANCE_ADMIN`
Assign execution Permission groups	Limited to the caller’s current memberships; `INSTANCE_ADMIN` can assign any group

USER_ADMIN and INSTANCE_ADMIN bypass the management ACL. Target rank still applies: an account with INSTANCE_ADMIN requires an instance administrator, and one with USER_ADMIN requires a user administrator. The API reevaluates these checks against current data for every mutation. Disable immediately when ownership is unclear or a credential may be exposed. Before permanent deletion, move any Jobs, Schedules, Agents, and external clients to a replacement principal.

Rotation runbook

Open API Keys, select a saved key, save any pending edits, and select Rotate. Choose a grace period in integer milliseconds: zero revokes the old credential immediately, and the maximum is 365 days. Choose whether the replacement inherits its expiration, receives a new date at least four hours ahead, or has no expiration. Rotation creates a new key record and identifier. The old record retains its credential and receives only the grace cutoff. The pair uses one key-quota slot. Another rotation is rejected while the predecessor remains valid. Existing expiration cannot be edited; choose a replacement expiration during rotation. Store the new secret immediately, deploy it to the consumer, verify an authenticated request, and monitor authorization failures. During grace, both credentials remain valid until the old key’s cutoff. Immediate rotation and key revocation also terminate affected Realtime connections; unrelated credentials are unaffected.

Automate through low-code

Use serviceAccount to manage accounts and keys without an external HTTP call. Account, Group, and Permission-group references accept names or explicit ID/name selectors. Key operations require the key’s userKeyId.

const account = await serviceAccount.create({
  name: 'erp-sync',
  memberships: { roleGroups: ['Integration runtime'] },
});
const key = await serviceAccount.createKey(account.userId, { name: 'ERP deployment', restricted: false });
await vault.create('ERP_API_KEY', { value: key.secret });

For a subsequent rotation, get the current key version and pass it to the native operation:

const current = await serviceAccount.getKey('erp-sync', input.userKeyId);
const { newKey } = await serviceAccount.rotateKey('erp-sync', current.userKeyId, {
  version: current.version,
  gracePeriodMs: 60000,
});
await vault.rotate('ERP_API_KEY', { value: newKey.secret });

The account and key changes use optimistic versions. Rotation and Secret storage are separate operations: verify the Secret update before changing the consumer, and choose a grace period that covers that handoff.

Production checklist

One account per system, environment, or trust boundary.
Explicit users and Groups in the management ACL.
Least-privilege Permission groups.
Explicit membership for restricted resources.
Separate keys per client deployment.
Documented rotation and emergency-disable procedure.
No unattended automation under a user identity.

See Permissions, Groups, and Secrets.

Application interfaces

Data

Files

Automation

Collaboration and realtime

Observability

Identity and security

Create a workload identity

Built-in System account

Ownership and management access

Design one account per trust boundary

Grant access

API keys

Expiry reminders and direct key links

Lifecycle and roles

Rotation runbook

Automate through low-code

Production checklist

​Create a workload identity

​Built-in System account

​Ownership and management access

​Design one account per trust boundary

​Grant access

​API keys

​Expiry reminders and direct key links

​Lifecycle and roles

​Rotation runbook

​Automate through low-code

​Production checklist

Create a workload identity

Built-in System account

Ownership and management access

Design one account per trust boundary

Grant access

API keys

Expiry reminders and direct key links

Lifecycle and roles

Rotation runbook

Automate through low-code

Production checklist