> ## 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, schedulers, 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 the user list | Yes | Hidden by default |

Because service accounts cannot log in interactively, they are hidden from the user list by default. They still appear as members of the groups they belong to, and you can add them to groups from **Add Members**. 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`, `nightly-diffs`). 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/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.