Message Ops

Service accounts are API-only principals used by automated workloads, CI/CD pipelines, and integrations that need persistent programmatic access to the platform.

What is a service account?

A service account is a managed user with userType: service_account. Unlike standard users:

• It cannot sign in to the web UI — the server enforces this at the session layer.
• It authenticates exclusively via a long-lived API token (prefixed sop_).
• It must have a Sponsor — a named, active standard user who is accountable for the account.
• It can optionally have an IP allowlist that restricts which source IPs are permitted to use its token.

Creating a service account

Administrators with user-management permission can create service accounts. In the admin console:

1. Navigate to Admin → Service accounts and click Create Service Account.
2. Set a Display name (used for identification only — the account cannot sign in).
3. Select a Sponsor using the search field. The Sponsor must be an active standard user.
4. Optionally add an IP allowlist — enter one CIDR per line (e.g. 10.0.0.0/8). Leave blank to allow all IPs.
5. Select Create Service Account. The account is created without a token — the Sponsor or an authorized administrator generates it separately.

Generating a token

An administrator generates the token from the service account’s detail page:

1. Open the service account in the admin console (Admin → Service accounts, then View).
2. Click Generate Token in the API token panel.
3. Copy the token immediately — it is shown once and cannot be retrieved later.

Sponsors without access to Admin use POST /api/v1/service-accounts/{serviceAccountId}/api-token with their own authenticated identity. Sponsorship does not grant access to the Admin console. See API authentication for authentication and scoped access.

Using the token

Include the token as a bearer header on every API request:

Authorization: Bearer sop_yourTokenHere

Tokens expire after the platform-configured duration (default 90 days). The expiry is visible in the admin console on the service account’s detail page. Regenerating a token immediately invalidates the previous one.

IP allowlist

When an IP allowlist is configured, any API request using the service account’s token from an IP not in the list is rejected with 401 Unauthorized. An auth.service_account.ip_denied event is written to the audit log, including the request IP and the service account ID.

To update the allowlist, go to the service account’s detail page in the admin console and use Edit IP Allowlist in the IP allowlist section. The update is a full replacement — all previous entries are replaced.

Forwarded client addresses are trusted only within the configured proxy CIDRs and hop limit. The API stops at the first untrusted hop; it does not trust an arbitrary leftmost header value. The operator must verify the actual ingress path before relying on this restriction.

Changing the Sponsor

If a Sponsor leaves the organisation or changes roles, an admin can reassign the Sponsor from the service account’s detail page with Change Sponsor. The new Sponsor must be an active standard user. The change is recorded in the audit log.

Audit trail

All service account activity is audited with actor_type: service. The Sponsor’s user ID is included in audit records so that responsibility can always be traced back to a named human user.

Key audit events:

• service_account.created — when the account is created (initial Sponsor is captured here)
• service_account.sponsor.changed — when the Sponsor is reassigned
• service_account.api_token.generated_by_sponsor / generated_by_admin (and the matching regenerated_by_* events) — token generation and rotation
• service_account.ip_allowlist.updated / cleared — IP restriction changes
• auth.api_token.success / denied / expired — authentication outcomes
• auth.service_account.ip_denied — IP allowlist rejection

Message-operation job attribution

New resubmit, move, and delete jobs submitted by a Service Account record submitted_by_type: service and the authenticated Service Account ID in submitted_by. Worker audit events use that durable identity; cancellation audit events identify the principal making the cancellation request. Standard-user jobs retain their existing email attribution (or user ID when no email is available).

Job lists, details, events, reports, and cancellation remain governed by permissions for the job’s environment. A submitter identity does not grant access by itself, and authorized standard users can inspect Service Account jobs in their environments.

Existing job records retain their original attribution, including older Service Account jobs recorded as user with a synthetic email. This correction applies to newly created jobs and does not rewrite historical jobs or append-only audit events.

Scoped roles and issuance requirements

A Sponsor’s permissions are not inherited by the account. Assign the account its own scoped roles. Broker operations additionally require a matching persisted service policy; a service account’s queue role alone does not supply one.

v1.7.1 limitation: there is no customer policy editor or policy CRUD API. Admin → Permissions is only a catalogue. Unless the required service policy already exists, broker automation cannot be enabled through these account-management steps alone. Ask the supplier whether an approved provisioning procedure is available before planning this integration; do not assume one exists or use Global Admin as a workaround. See queue access and policy limits. Human-owned personal tokens with manual queue assignments provide a separate path for queue integrations.

Token issuance/rotation requires an authenticated, recently MFA-verified human session. A sop_ token cannot itself complete interactive step-up. Sponsors without administrative UI access can use POST /api/v1/service-accounts/{serviceAccountId}/api-token through their authenticated session; an administrator can use POST /api/v1/admin/users/{userId}/api-token with the required token-management permission and authority over the account. See API authentication.