Service Accounts & API Credentials

Service Accounts & API Credentials

1. What it is

Service accounts are non-human user principals used for API integrations, automation bots, and AI agent attribution. Each service account has its own identity, role, and API tokens — separate from any human user’s credentials. This keeps integration access auditable and revocable without touching a person’s account.

• Enablement: Service accounts are a built-in admin feature — no marketplace app licence is required.
• What it is not: A service account is not a shared login for a team. It cannot be assigned the Super Admin role, and it does not count toward your human user seats.

2. Standing it up

1. Go to Admin → Security → Service Accounts (the admin sidebar, under the Security section).
2. Click New Service Account and fill in:
   • Name — a descriptive label (must be unique among service accounts in your business).
   • Purpose — Automation (API/integration principal) or AI agent (in-product attribution).
   • Access level — Read-only (default) limits all tokens on this account to read: scopes only. Read-write allows any scope.
   • Login — Token only (default, recommended) blocks all interactive web/SSO login. Web + token also allows browser login, subject to IP and device restrictions.
   • Role — Member (default), Manager, or Admin. This is the platform role for permission checks; API power comes from token scopes, not the role.
   • Description — free-text note visible on the account detail page.
3. After creation, go to the account’s detail page and issue an API token (see §4 below). The account exists but cannot authenticate until it has at least one active token.
4. Confirm the integration works by checking the token’s Last used timestamp on the detail page.

Silent-until-configured: a service account with no active tokens cannot call any API endpoint. Creating the account alone does not grant API access.

No edit or delete in the admin UI. Once created, a service account’s Access level, Login, Purpose and Role cannot be changed. There is no delete action — to decommission an account, revoke all its tokens. If different settings are needed, create a new account and migrate the integration.

3. How it fits together

A service account is a user, flagged as a system account. Under the hood it is an ordinary user record marked as a system account, with a companion profile holding its service-account settings. It has a synthetic email address on the .invalid top-level domain (guaranteed undeliverable), a random password it never uses, and is excluded from:

• The normal user directory and user-count reports.
• All notification delivery — notifications stop before they reach a service account.
• All email delivery — the .invalid address is caught by the outbound mail guard.
• Two-factor authentication requirements — service accounts are always exempt.

This means service accounts do not consume user seats and will never generate stray notifications or emails.

Access level is a ceiling, not a grant. The Access level (Read-only or Read-write) chosen for the account is an upper bound over every token on it. A read-only account’s tokens can only hold read: scopes — the system refuses to save a token with any non-read: scope. A read-write account’s tokens can hold any scope, but each token still declares its own explicit scope list.

Tokens require explicit scopes. Unlike personal API tokens (where blank scopes means full access), service account tokens must declare at least one scope. This prevents accidental full-access grants. Two broad scopes are available: admin grants access to all endpoints, and read:all grants every read: scope.

Token authentication is two-part. Each token has both a token ID and a secret. Both are shown once at issuance and stored as SHA-256 digests — neither can be retrieved afterward. API requests must present both values. A request with only the token and no secret will not authenticate.

Purposes. Each account has a purpose that describes how it is used:

• Automation — the default; used for API integrations and bots.
• AI agent — carries attribution for in-product agent actions. Created automatically by the platform when an agent first runs (one per business, named “AI Agent”).
• Chat assistant — the “@Ask AI” reply principal in the Chat app. Created automatically; identified by purpose, so renaming the assistant’s display name does not break resolution.

Admins create Automation accounts manually. AI agent and Chat assistant accounts are provisioned automatically on first use and do not need manual setup.

Name uniqueness. Service account names must be unique within a business — the platform enforces this at the storage layer, so duplicates cannot be created. The rule applies only among service accounts; a service account can share a display name with a human user.

4. Running it

Issuing a token

1. Open the service account’s detail page (Admin → Security → Service Accounts → click the account).
2. In the Issue a token section, enter a token name, choose an expiry (30 days, 90 days, 1 year, or never), and select the scopes this token should have.
3. Click Issue. The plaintext token and secret are shown once in an alert banner at the top of the page. Copy both immediately — they are stored as SHA-256 digests and cannot be retrieved again.

The integration authenticates by presenting both the token and the secret. Either value alone is not sufficient.

Scopes are grouped into categories on the issuance form: own-data scopes covering only that account’s own profile, shifts and timesheets; manager and admin scopes over everyone’s data (e.g. read:users, write:shifts); app-specific scopes (e.g. read:inspections, write:forms, read:wikis); and MCP scopes for agent tool access. A filter and select-all/clear controls help manage the full list. The available scopes shown depend on the account’s Access level — Read-only accounts see only read: scopes.

Rotating a token

On the account’s detail page, click Rotate next to the active token. This issues a replacement token with the same name, scopes, and expiry, then immediately revokes the old one. The new plaintext credentials are shown once.

Revoking a token

Click Revoke next to any active token. Revocation is immediate — the token’s expiry is moved to the current moment. Revoked tokens remain visible in the list with a “Revoked” status badge.

Configuring IP restrictions

On the account’s detail page, under Access restrictions:

1. Enable IP restricted to require that all API requests (and web logins, if allowed) come from specific IP addresses or CIDR ranges.
2. Enter allowed IP ranges, one per line.
3. Optionally enable Include business IP ranges to also accept the IP ranges configured at the business level (under Admin → Security).

IP enforcement is fail-closed: if IP restriction is enabled and no ranges match, the request is rejected. This applies at both the API layer and the web login layer. The API returns:

403 Forbidden — error code: ip_not_allowed

Configuring device restrictions

Device restriction is available only for accounts with Web + token login. When enabled, a web login attempt from an unrecognized device is blocked. The device appears as “recognized” on the account’s detail page, and an admin must click Trust to promote it to verified status before the account can log in from that device.

Monitoring token expiry

A daily background job (runs at 7:30 AM UTC) checks for service account tokens expiring within 14 days. Admins and super admins receive an in-app notification at two windows: 14 days and 3 days before expiry. Each reminder fires once per token per admin per window — it does not repeat daily within a window. The notification links directly to the account’s detail page where the token can be rotated.

How web login works for service accounts

When a service account’s Login is set to Web + token, the account can log in through the normal password form. However, several restrictions apply:

• Token-only accounts are always blocked from web login — on both the password form and any SSO/magic-link path.
• IP-restricted accounts are blocked if the request IP is not in the effective allowlist.
• Device-restricted accounts are blocked if the browser’s device is not yet trusted. The login attempt registers the device as “recognized”, and an admin must explicitly trust it from the account’s detail page before the next login attempt will succeed.

5. Settings

Setting	Where	Default	What it changes
Access level	Set at creation	Read-only	Ceiling on token scopes — Read-only accounts can only hold read: scopes
Login	Set at creation	Token only	Whether the account can also log in interactively via web/SSO
Role	Set at creation	Member	Platform role for permission checks (Member, Manager or Admin — never Super Admin)
IP restricted	Account detail → Access restrictions	Off	When on, API requests and web logins must come from an allowed IP
Include business IP ranges	Account detail → Access restrictions	On	When IP restricted, also accept the business-wide IP allowlist
Device restricted	Account detail → Access restrictions	Off	When on (web+token accounts only), web login requires admin-approved device

Access level, Login and Role are set at creation and cannot be changed through the admin UI afterward. To change these, create a new service account with the desired settings, migrate your integration to the new account’s tokens, then leave the old account’s tokens revoked.

Defaults are applied by the platform, not the form: every new account starts at Read-only access, Token only login, IP restricted off, Include business IP ranges on, and Device restricted off. These defaults are applied at the storage layer — they hold regardless of what the form shows.

6. More help

• Service Accounts FAQ — specific setup and operating questions (not yet published)
• Admin → Security → API Keys & Access — personal API tokens for human users (separate from service account tokens)
• Service account API tokens are subject to the same rate limits as all API tokens (per-token and per-IP throttles).
• Ask AI — the assistant answers questions about service accounts from this article.