Service Accounts for Integrations and Embedding

A service account is a Yurbi user that belongs to a system rather than a person: an API integration, the account your application signs in with to embed dashboards, a scheduled export, or the user that Server Sync uses to copy content between servers. These accounts sign in automatically with a stored password and cannot answer a two-factor prompt or choose a new password on screen.

Marking an account as a service account tells Yurbi to never interrupt it with those steps, so turning on two-factor authentication or forcing a password change for everyone does not silently break an integration.

What a service account skips

Interruption

Normal user

Service account

Two-factor prompt at sign-in (Optional mode, if enrolled)

Asked

Skipped

Two-factor enrollment (Required mode)

Must enroll

Skipped

Require password change at next login

Must change

Skipped

Forced password change for all users (API)

Must change

Skipped

Every skipped two-factor step is written to the Audit Log as Two Factor Skipped, so a security review can see which sign-ins bypassed 2FA.

What a service account does not skip

  • Account lockout. Five wrong passwords still lock it for 5 minutes. A stale stored password will lock the account; rotate passwords deliberately and update every place the password is stored.

  • Password security rules. When you set its password, the same 12-character and breach-screening rules apply.

  • Disabled. A disabled service account cannot sign in.

  • Permissions and licensing. It is an ordinary user in every other respect.

When to use one

Create a dedicated user and mark it as a service account for each of these:

  • API integrations that sign in through the API with a stored username and password.

  • Embedding. The account your host application signs in with to show dashboards or reports to end users. If each end user has their own Yurbi account, those accounts need to be service accounts too — the embed signs in as that user, and a user who is required to use 2FA cannot be embedded otherwise.

  • Server Sync. The sync service signs in to the destination server about every five minutes with the username and password you entered when registering the server. The Server Sync guide already recommends a dedicated user on the source and on each destination; make both of them service accounts. See Understanding Server Sync.

  • Scheduled exports or scripts that run under a Yurbi login.

Give each integration its own account rather than sharing one. Yurbi keeps one session per user, so two systems sharing an account sign each other out.

Marking an account as a service account

  1. Go to Settings → Security → Users and open the user (or create it).

  2. Under Additional Options, turn on Service account (API integration).

  3. Click Save & Apply.

The Users list shows a Service pill for the account. Turning the switch off restores normal behavior at the user's next sign-in.

Rules:

  • You cannot mark your own account as a service account.

  • The built-in admin account can only be marked by itself — a lesser administrator does not see the switch for it — and the editor shows a warning, because admin is the account you recover the system with. Avoid using it for integrations at all.

  • Only administrators can set or clear the switch. Each change is recorded in the Audit Log (Service Account Set / Service Account Cleared).

Keeping service accounts secure

Because a service account skips two-factor, its password is the only secret protecting it:

  • Use a long random password (32+ characters) and store it only in your integration's secret store.

  • Give it the least access it needs — an application role and group membership for the content it uses, not administrator rights unless the integration manages users.

  • Rotate the password on a schedule you control, updating the integration first, rather than through a forced change.

  • Disable it when the integration is retired; disabling keeps the audit history.

  • Prefer SSO or the External authentication method where your identity provider can authenticate the integration instead.

Troubleshooting

The integration started failing after we turned on Required two-factor. Its account is not a service account. Mark it as one; the next sign-in completes without a prompt. (If you are the integration's developer: the sign-in response during the outage carried requiresTwoFactor or requiresTwoFactorEnrollment as true.)

Server Sync shows no status after a security change. Check the sync user on the destination server: it must not be disabled, locked, flagged for a password change or required to use 2FA. Then re-enter the password on the registered server entry (it is not shown when editing) and use Test Connection.

The account keeps getting locked. Something is retrying an old password. Find every place the credential is stored, update it, then unlock the account from the Users list.

Related