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

# Service accounts & OIDC trusts

> Machine identities and the OIDC trusts that let CI authenticate without stored secrets

A **service account** is a non-human member of an organization, assigned a role (its scopes). An **OIDC trust** lets an external workload (e.g. a GitHub Actions run) exchange its OIDC token for a short-lived Synthetiq token that acts as a service account — no stored credentials. This is the identity model behind [BYOI CI provisioning](/docs/platform-docs/deployments/byoi/ci-integration).

**Node SDK:** `sdk.serviceAccounts.*` and `sdk.oidcTrusts.*`. See [Node SDK](/docs/platform-docs/platform-api/node-sdk).

## Service accounts

### List service accounts

```bash theme={null}
GET /api/organizations/{id}/service-accounts
```

Returns the organization's service accounts, each with its role and OIDC trusts.

**Authentication:** Organization member + `org:service-accounts` scope (token: `platform:orgs:service-accounts:read`).

### Create service account

```bash theme={null}
POST /api/organizations/{id}/service-accounts
```

| Parameter | Type | Required | Description                          |
| --------- | ---- | -------- | ------------------------------------ |
| `name`    | body | Yes      | Display name for the service account |
| `role_id` | body | Yes      | Role granting the account its scopes |

**Authentication:** Organization member + `org:service-accounts` scope (token: `platform:orgs:service-accounts:write`).

### Update service account

```bash theme={null}
PATCH /api/organizations/{id}/service-accounts/{userId}
```

| Parameter | Type | Description      |
| --------- | ---- | ---------------- |
| `name`    | body | New display name |
| `role_id` | body | New role         |

**Authentication:** Organization member + `org:service-accounts` scope.

### Delete service account

```bash theme={null}
DELETE /api/organizations/{id}/service-accounts/{userId}
```

**Authentication:** Organization member + `org:service-accounts` scope.

## OIDC trusts

A trust binds an `(issuer, subject)` pair to a service account. When a request presents an OIDC token whose issuer and subject match, the platform mints a Synthetiq token for that service account.

### List OIDC trusts

```bash theme={null}
GET /api/organizations/{id}/oidc-trusts
```

**Authentication:** Organization member + `org:trusts` scope (token: `platform:orgs:trusts:read`).

### Create OIDC trust

```bash theme={null}
POST /api/organizations/{id}/oidc-trusts
```

| Parameter     | Type | Required | Description                                                             |
| ------------- | ---- | -------- | ----------------------------------------------------------------------- |
| `user_id`     | body | Yes      | Service account the trust authenticates as                              |
| `issuer_url`  | body | Yes      | OIDC issuer (e.g. `https://token.actions.githubusercontent.com`)        |
| `subject`     | body | Yes      | Exact subject claim to match (e.g. `repo:org/repo:ref:refs/heads/main`) |
| `description` | body | No       | Human-readable label                                                    |
| `jwks`        | body | No       | Static JWKS, for issuers without a discovery endpoint                   |

The `subject` is the security boundary — keep it exact (a specific repo and ref), never a wildcard.

**Authentication:** Organization member + `org:trusts` scope (token: `platform:orgs:trusts:write`).

### Update OIDC trust

```bash theme={null}
PATCH /api/organizations/{id}/oidc-trusts/{trustId}
```

Updates `issuer_url`, `subject`, `user_id`, and/or `description`.

**Authentication:** Organization member + `org:trusts` scope.

### Delete OIDC trust

```bash theme={null}
DELETE /api/organizations/{id}/oidc-trusts/{trustId}
```

**Authentication:** Organization member + `org:trusts` scope.

## See also

* CLI equivalents: [`synthetiq service-account`](/docs/platform-docs/cli/service-account) and [`synthetiq trust`](/docs/platform-docs/cli/trust)
* [BYOI Service Account setup](/docs/platform-docs/deployments/byoi/service-account)