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

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

```bash theme={null}
curl https://app.datafold.com/api/v1/... -H "Authorization: Key {API_KEY}"
```

See the [API Introduction](/api-reference/introduction) 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 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.