Service Accounts | Alephant Documentation

Service accounts are used by background jobs, connector syncs, automations, and external integrations. Because they do not represent a human user, each account needs a clear owner, scope, and rotation plan.

Management Boundary

Area	Guidance
Ownership	Bind each account to a team or business owner instead of a personal admin.
Permissions	Grant only the roles and resources required for the target task.
Lifecycle	Track creation, rotation, disablement, and deletion.
Audit	Trace requests by account name, purpose, source, and result.

Account and Key Types

Choose the narrowest credential that can complete the integration. A service account should make machine-to-machine access auditable without turning every automation into a full administrator.

Type	Use it for	Governance notes
Admin service account	Tenant administration, user or group operations, bulk configuration, and operational maintenance.	Use only for trusted automation. Store it in a managed secret store, review it frequently, and remove it when the workflow no longer needs administrative reach.
Standard service account	Application integrations that call non-admin APIs, run approved workflows, use agents, or connect internal systems.	Prefer this type for most production integrations. Scope it to the owning team, workspace, connector, agent, or resource set whenever possible.
Restricted service account	Read-only, single-purpose, or test integrations that only need a narrow subset of access.	Use for low-trust environments, staged rollouts, and integrations that should fail closed outside one approved action path.

Avoid sharing one credential across departments, environments, or vendors. Separate accounts make request history, cost attribution, incident response, and offboarding much easier to reason about.

Before Configuration

Identify the APIs, connectors, or background jobs the account will call.
Confirm it does not need to impersonate an admin, end user, or bot.
Define where secrets are stored, how often they rotate, and how they are revoked.
Decide whether the integration needs admin, standard, or restricted access.
Name the account after its system and purpose, such as crm-sync-prod or billing-export-readonly.
Record the environment, owner, allowed source network, and expected request pattern before issuing the key.

Create and Store a Credential

Open the AIvis admin area and go to the service accounts or API keys page.
Create a new account or key for the integration and select the smallest access type that matches the task.
Copy the secret immediately after creation and store it in your approved secret manager.
Add only the credential reference to application configuration. Do not paste the raw secret into code, tickets, runbooks, chat, or screenshots.
Run the first request from the approved runtime environment, not from a personal laptop, unless the account is explicitly for local development.

If the credential is exposed, disable or delete it first, then create a replacement. Do not rely on renaming the account or changing its description as a containment step.

Rotation and Removal

Operation	When to use it	Required follow-up
Rename	The owner, purpose, or environment label is unclear.	Confirm logs and dashboards still identify the integration correctly.
Regenerate	A planned rotation is due, a secret may have been copied into an unsafe place, or the owning system changed hands.	Deploy the new secret, verify the integration, then revoke the old value.
Disable	You need a reversible pause during an incident, vendor handoff, or maintenance window.	Watch for denied requests and confirm the dependent job fails closed.
Delete	The integration, vendor, environment, or automation is retired.	Remove the secret from the external system and keep the audit record for the retention period.

Verification

Validate the account with a read-only request.
Validate that out-of-scope requests are denied.
Confirm tracing or query history can identify requests made by the account.
Confirm cost, usage, and audit views attribute traffic to the service account instead of a personal admin.
Confirm rotation and revocation procedures are documented where the owning team operates the integration.

Production Checklist

One service account per integration, environment, and trust boundary.
No personal administrator accounts are used for scheduled jobs or connector syncs.
Admin credentials have an explicit business owner, expiration review, and storage location.
Restricted credentials cannot read unrelated chat history, knowledge sources, or administrative configuration.
Incident response instructions include where to revoke the key and how to replay the affected job after replacement.