Service accounts are organization-managed machine identities. They own API keys for automation — CI pipelines, dbt jobs, scripts, third-party integrations — without tying those keys to a human user who might leave the team.
How service accounts differ from user accounts
| User account | Service account |
|---|
| Web UI login | Yes (password or SSO) | No — API keys only |
| Email | Real mailbox | Non-deliverable synthetic address |
| Invitation flow | Email invite required | Created directly by an admin |
| Permissions | Via groups or role | Via groups (required) |
| API keys per account | Up to 5 | Up to 50 |
| Visible in user lists, groups, and subscriptions | Yes | Hidden |
Create a service account
Only organization admins can manage service accounts.
- Open the Datafold app and navigate to Settings → Service Accounts.
- Click Create Service Account.
- Fill in:
- Name — a short identifier (e.g.,
ci-bot, dbt-cloud-prod). Shown in audit logs and the Service Accounts list.
- Description (optional) — a free-form note to document what the account is used for.
- Groups — at least one permission group is required. The service account inherits all permissions from the groups you select.
- Click Create. The account appears in the list immediately. No API keys are issued yet.
A service account with no groups would have no permissions at all, so the form requires at least one. If you need a different permission set, create a new group under Settings → Groups first.
Issue API keys
From the Service Accounts list, click API Keys on the relevant row. A service account can have up to 50 active API keys, which is intentionally higher than the per-user limit so you can issue one key per CI environment, region, or deployment without collapsing them together.
Each key can be given:
- A name for identification.```
- An optional description for your own reference.
- An optional expiration (in days). Leave unset for a non-expiring key.
The key value is shown only once at creation — copy it into your secret store immediately.
Using a service account API key
Service account keys are used exactly the same way as personal API keys. Include the key in the Authorization header:
curl https://app.datafold.com/api/v1/... -H "Authorization: Key {API_KEY}"
Lifecycle
| Action | Effect |
|---|
| Disable | All of the account’s API keys immediately stop working. The account and its keys remain in place and can be re-enabled. Use this to pause an integration without losing the key set. |
| Enable | Restores a disabled service account. Existing keys resume working immediately. |
| Edit | Change the name, description, or permission groups. Permission changes take effect on the next authenticated request. |
| Delete | Permanently revokes all of the account’s API keys and removes the account. This cannot be undone. |
Permissions
A service account’s permissions are the union of the groups assigned to it. To change what a service account can access:
- Change the account’s group assignments under Settings → Service Accounts (admin-only).
- Or change what a group can access under Settings → Groups — every account (human or service) in that group picks up the change.
Service accounts ignore the admin, default, and viewonly role flags. Grant admin-level access only by putting the account in a group that has those permissions.
Best practices
- One service account per automation surface. A separate account for CI, for your ETL scheduler, and for each third-party integration makes it obvious in audit logs who did what, and lets you rotate or disable one surface without affecting the others.
- Scope via groups. Give a service account only the groups it needs — a CI-only account does not need access to production monitors.
- Name keys after where they run.
ci-bot with keys named github-actions-prod, github-actions-staging, etc. makes rotation obvious.
- Rotate keys on offboarding-equivalent events. When a CI runner is decommissioned, a deployment region is retired, or a secret may have been exposed, revoke the specific key rather than the whole account.
- Disable, don’t delete, for temporary pauses. Deletion is permanent; disable is reversible.
