> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datafold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Accounts

> Machine identities for CI, integrations, and scripts. Service accounts own their own API keys, inherit permissions from groups, and are managed independently of human users.

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 |

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.

> [!NOTE]
>
> 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** (1–365 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:

```bash theme={null}
curl https://<your Datafold host>/api/v1/... -H "Authorization: Key {API_KEY}"
```

See the [API Introduction](https://docs.datafold.com/classic/api-reference/introduction.md) for the full authentication reference.

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

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 get permissions only from their groups. To grant admin access, add the account to the built-in `admin` group.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.