Skip to main content
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

Because service accounts cannot log in interactively, they are invisible in the user directory and cannot be added to Slack/email subscription targets — they only exist to hold API keys.

​
Create a service account

Only organization admins can manage service accounts.
  1. Open the Datafold app and navigate to Settings → Service Accounts.
  2. Click Create Service Account.
  3. 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.
  4. 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:
See the API Introduction for the full authentication reference.

​
Lifecycle

Individual API keys can be revoked from the API Keys modal without affecting the account itself — useful when rotating a single leaked key.

​
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.