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.