Service Accounts

Service accounts are non-human principals for production workloads. A service account owns one or more service-account tokens (fx_sat_...) and carries its own explicit scope grant, so a CI job, webhook, backend service, or customer automation does not have to act as a human user.

Principal vs. credential

A service account is the principal: the actor Fruxon records in audit logs. A service-account token is the credential: the secret a workload sends to the API.

This split matters:

• The service account has the durable identity, display name, description, and scope grant.
• Tokens owned by that account can be rotated without changing which workload principal is acting.
• Revoking the service account rejects every token it owns, even if a token secret still exists somewhere.
• Request activity stays attached to the token, while principal lifecycle history stays attached to the service account.

Personal token or service account?

Create a service account

Open Settings -> API Access -> Service accounts -> Create service account.

1. Name the workload, such as prod-agent-runner, nightly-evals, or stripe-webhook.
2. Add an optional description explaining what owns it and where the token is stored.
3. Pick a preset or explicit scopes.
4. Set an optional token expiry.
5. Copy the first fx_sat_... token immediately; it is shown once.

Scope safety

Creating or rotating service-account credentials is an administrative action. The scope grant cannot exceed the authority of the user performing the operation, so a user cannot mint a workload credential with permissions they could not exercise themselves.

Use the same scope vocabulary as personal tokens. See Tokens -> Scope vocabulary for the full list and presets.

Use a service-account token

Use the fx_sat_... token exactly like any other Fruxon token:

curl -X POST "https://api.fruxon.com/v1/tenants/{tenant}/agents/{agent}:execute" \
  -H "Authorization: Bearer $FRUXON_SERVICE_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"ticket": "TCK-1842"}}'

Rotate credentials

Rotating a service account mints a fresh fx_sat_... token and revokes the account's other active tokens. The new token is live before old tokens are retired, so you can update your secret manager and restart consumers without changing the principal.

curl -X POST "https://api.fruxon.com/v1/tenants/{tenant}/serviceAccounts/{serviceAccount}:rotate?keyExpirationDays=90" \
  -H "Authorization: Bearer $FRUXON_TOKEN"

The response includes the new token secret once.

Revoke a service account

Revoking the account marks the principal inactive and cascade-revokes every token it owns. Use this when a workload is retired, compromised, or no longer has a clear owner.

If you only need to replace a leaked token while keeping the workload alive, rotate instead.

Audit history

Service-account lifecycle events include provision, rotate, revoke, and used-while-revoked attempts. View them from the account details drawer in Settings or fetch them directly:

curl -X GET "https://api.fruxon.com/v1/tenants/{tenant}/serviceAccounts/{serviceAccount}/auditEvents" \
  -H "Authorization: Bearer $FRUXON_TOKEN"

Per-request activity for a specific token lives under Tokens -> Audit and activity.

Endpoint reference

Best practices

• Name accounts after workloads, not people. billing-sync-prod is easier to audit than sarah-token.
• Keep grants narrow. Use runner for execution, read-only for dashboards, and explicit scopes for webhooks.
• Store tokens in a secret manager. Never commit the full fx_sat_... value or paste it into prompts.
• Rotate on ownership changes. Rotate when the team, deployment target, or secret manager path changes.
• Delete dead workloads. If no service owns it, revoke it.

Next steps

• Tokens — bearer auth, scopes, rotation, and activity logs
• Settings — API Access navigation
• Security — credential protection and audit posture