govoplan-access/docs/SERVICE_ACCOUNTS.md

Service accounts

Service accounts are tenant-owned, non-login principals for automation. Their backing account and membership cannot use a password or browser session.

Authorization model

The service account defines a revisioned scope ceiling. Every credential has its own narrower scope grant. On every authenticated request, Access checks that the tenant, service account, backing account, membership, and credential are active, then grants only the intersection of the current ceiling and the credential scopes. Reducing the ceiling therefore takes effect without reissuing a credential.

Administrators may grant only scopes they currently hold. Credential creation also follows the tenant API-key governance switch. Secrets are returned once; the database stores a one-way hash and a non-authenticating prefix.

Administration

Open Admin > Tenant > Service accounts to create, edit, deactivate, activate, or retire a principal. The detail dialog lists active, expired, and revoked credentials and exposes create, rotate, and revoke actions.

Every write includes expected_revision. A concurrent change returns 409 and the UI reloads the account before another action. Rotation creates the new credential and revokes the old one in a single transaction. Retirement deactivates the principal and revokes all active credentials.

API

• GET/POST /api/v1/admin/service-accounts
• GET/PATCH /api/v1/admin/service-accounts/{service_account_id}
• POST /api/v1/admin/service-accounts/{service_account_id}/retire
• GET/POST /api/v1/admin/service-accounts/{service_account_id}/credentials
• POST /api/v1/admin/service-accounts/{service_account_id}/credentials/{credential_id}/rotate
• POST /api/v1/admin/service-accounts/{service_account_id}/credentials/{credential_id}/revoke

Credential list responses never contain a secret. Create and rotate responses contain it once. Audit records include identifiers, prefixes, scopes, and the new service-account revision, but never the secret or its hash.

Contextual help

F1 on the service-account page, its editors, scope controls, one-time secret, rotation and revocation actions, activation state, or retirement confirmation resolves to the Access-owned access.workflow.manage-service-account-credentials topic. The German reference content distinguishes reversible deactivation from retirement, explains immediate client impact, and states that secrets cannot be recovered. Tenant API-key controls resolve separately to access.workflow.manage-api-keys, because their effective authorization also depends on the accountable human owner's current permissions.