Introduction to Service Accounts

A Service Account is a programmatic identity used by automated systems, CI/CD pipelines, and infrastructure tooling to interact with the Zaita control plane API. Unlike Couriers — which authenticate using federated machine identities — Service Accounts authenticate via a static client_id / client_secret credential pair and receive a time-limited session token for subsequent API calls.

Service Accounts are intended for tooling that needs to query or manage the platform programmatically, such as enforcing certificate policies via IaC pipelines, pre-validating certificate requests in CI workflows, or integrating with external PKI tooling.

Key Properties

Property	Description
Tenant-scoped	Each Service Account belongs to exactly one tenant; all operations are filtered accordingly
Credential-based	Authenticates with a static client_id and client_secret (bcrypt-hashed at rest)
Scope-controlled	Access is governed by read, write, and admin scopes with a strict inheritance hierarchy
IP-restrictable	Optional allowlist of exact IPs or CIDR ranges; requests from outside the allowlist are rejected at authentication time
Expirable	Optional expiry date; expired accounts are automatically treated as inactive
Session-oriented	Authentication produces a 24-hour session token; credentials are not sent on every request

Intended Use Cases

• Automated certificate policy management via IaC pipelines (Terraform, Ansible)
• CI/CD pre-validation of certificate requests before issuance
• Certificate lifecycle reporting and inventory queries
• Integration with external tooling that requires programmatic PKI access

Service Accounts vs. Couriers

Service Accounts are not a replacement for Courier authentication. Couriers should continue to use federated identity methods (SPIFFE/SPIRE, Azure Workload Identity, AWS IAM OIDC, etc.) wherever possible.

	Service Account	Courier
Identity type	Static credential pair	Federated machine identity
Primary use	API automation, IaC, CI/CD	On-premises certificate delivery
Authentication	client_id + client_secret	SPIFFE, Azure, AWS IAM, and others
Session TTL	24 hours	Per-authentication
Scope control	read, write, admin	Certificate pull operations

Service Accounts are best suited for non-Courier automation that interacts with the platform API directly.

Scopes

Service Account access is governed by three scopes arranged in a strict hierarchy:

Scope	Grants access to
read	Read-only operations (list, get)
write	All read operations, plus create, update, enable/disable, and delete
admin	All write operations, plus administrative actions

A Service Account granted write scope automatically satisfies any read requirement. An admin-scoped account satisfies all scope checks.

Assign the minimum scope required for the intended use case. CI/CD pipelines that only validate certificate requests require only read.