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

# Users, groups, and service accounts

> How human users, groups, and service accounts are created, synced to workspaces, and managed in e6data.

e6data has three identity types: **users** (humans), **groups** (collections of users or service accounts assigned roles together), and **service accounts** (non-human identities for automation). All three participate in the same role-based access control - see [Control Plane vs Compute Plane permissions](/platform/identity/control-plane-vs-compute-plane).

Identities and group memberships are managed on the Control Plane and synced to each workspace automatically, typically within about 30 seconds.

## Users

A user has one global identity but belongs to your organization (and possibly others) with **per-organization** roles and block status. A user can be Admin in one organization and Viewer in another.

### How a user joins your organization

* **Invitation.** An admin with `write:invitations` invites the user by email; they accept via a one-time link and pick a sign-in method.
* **First-user bootstrap.** The first user of a new organization is automatically assigned the Admin role.
* **SSO just-in-time (JIT).** If SSO is configured with domain auto-join, a user signing in with a matching email domain is provisioned on first login with the SSO default role. See [Domain auto-join and JIT provisioning](/platform/identity/domain-auto-join-and-jit).

Invite a user over the API:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/invitations
{
  "email": "alice@acme.com",
  "roles": ["manager"]
}
```

Required permission: `write:invitations`. If `roles` is omitted, the user defaults to **Viewer**.

### Sign-in methods

| Method | When |
| - | - |
| SAML / OIDC SSO | If your org has SSO configured. Recommended for larger orgs. |
| Email OTP | Default - a one-time code emailed to the user. |
| Password | Available; can be disabled per-org when SSO is mandated. |

### Reaching a workspace

The Control Plane is the source of truth. Each workspace pulls user and group changes automatically (about every 30 seconds), so a role binding that references a user's email becomes effective once the user is synced - you don't re-bind after a user appears. Control Plane permissions do **not** become Compute Plane permissions: a Control Plane admin must still be granted workspace role bindings to do anything inside a workspace.

### Block and unblock

A **block** immediately denies a user entry while preserving their roles, so you can restore access by unblocking:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/users/{userId}/block      # permission: write:users
POST /api/v1/users/{userId}/unblock    # permission: write:users
```

Blocks are per-organization. A user blocked in your org cannot switch into it (`403`); a user blocked in *every* org they belong to cannot log in at all (`401`). You cannot block yourself or the organization owner.

### Other lifecycle notes

* **Changing an email** keeps the user's underlying identity, so role bindings, audit history, and group memberships continue to work.
* **Removing a user** drops their membership; they can rejoin later via invitation.
* Every change (invited, joined, role added/removed, blocked, removed, profile changed) is recorded with the acting user and timestamp.

## Groups

A **group** is a flat collection of users (and, on the Compute Plane, service accounts) assigned roles collectively. Instead of binding each user to a role, bind the group once and manage membership.

Groups solve two problems: per-user binding explosion (a 50-person team needing the same access is one set of group bindings, not 50× the bindings) and drift (remove a member once and every workspace updates within \~30 seconds).

A group can carry **both** Control Plane role bindings (org-level APIs) and Compute Plane role bindings (data operations), tracked separately because the permission vocabularies differ. Manage groups over the API:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST   /api/v1/groups                    # create  (write:groups)
POST   /api/v1/groups/{id}/members       # add members (write:groups)
POST   /api/v1/groups/{id}/roles         # bind a role (write:groups + manage:roles)
DELETE /api/v1/groups/{id}/members/{uid} # remove a member
```

Groups are flat (no group-of-groups) and per-organization. Adding a member grants them all of the group's roles across every workspace within \~30 seconds. If you map IdP groups to e6data roles via SSO, membership flows automatically on sign-in.

## Service accounts

A **service account** is a non-human identity scoped to a **single workspace**, used for automation (CI/CD, scheduled jobs). It authenticates with an `e6sa_` API key and is governed by the same role bindings as users.

| Use case | Identity to use |
| - | - |
| CI/CD or a scheduled job in one workspace | Service account (`e6sa_`) |
| A developer's own scripts | Personal access token (`e6pat_`) |
| Cross-workspace automation | One service account per workspace (they don't span workspaces) |

Create a service account and issue a key over the API:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/service-accounts
{ "name": "ci-pipeline", "displayName": "CI Pipeline", "description": "Deployment bot" }

POST /api/v1/service-accounts/ci-pipeline/keys
```

The name is permanent (lowercase letters, digits, and hyphens; 1–63 characters). A key's secret is shown **once** at creation. Deleting a service account revokes all its keys and removes its bindings. Grant a service account the **minimum** role it needs, use one per system, and rotate keys with create-before-delete. For the full token lifecycle, see [Access tokens](/platform/tokens/pat-and-service-account-keys).

## See also

* [Roles and permissions](/platform/identity/roles-and-permissions)
* [Control Plane vs Compute Plane permissions](/platform/identity/control-plane-vs-compute-plane)
* [Access tokens](/platform/tokens/pat-and-service-account-keys) - `e6pat_` and `e6sa_` credentials.
* [Support access](/platform/support-access/enable-audit-block) - e6data engineer identities.


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