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

# Service accounts

> Create machine identities that hold scopes directly and authenticate to the Tracecat REST API with an API key.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

## Overview

A service account is a machine identity that holds scopes directly, with no role. Organization service accounts live under Service accounts in the organization sidebar at `/organization/settings/service-accounts`, and workspace service accounts at `/workspaces/{id}/service-accounts`.

The sidebar entry appears only when you hold the service account read scope for that level.

## Create a service account

Select `Create service account`. The dialog takes a name, an optional description, an `Initial key label` (default `Primary`), and the same category permission picker the role dialog uses — see [Custom roles and groups](/manage-platform/custom-roles#create-a-role) for the categories and levels.

On create, Tracecat shows the key once in a `Copy API key` dialog: `This secret is only shown once. Copy it now before closing this dialog.` Organization keys are prefixed `tc_org_sk_` and workspace keys `tc_ws_sk_`.

## Manage a service account

The list shows each account's status — Active, Disabled, or No active key — with its scope and key counts and a last-used time, and filter chips narrow the list.

`Issue new API key` revokes the current key and issues a replacement, because a service account holds at most one active key. Tracecat refuses issuing a key on a disabled account with `Disabled service accounts cannot generate new API keys`.

`Disable` stops the account authenticating immediately and `Enable` restores it. Keys and accounts never expire, and disable and revoke are the only lifecycle controls — there is no delete.

## Scopes

Each kind of service account draws from its own allowlist. A workspace service account can hold the workspace resource scopes for agents, cases, integrations, schedules, secrets, tables, tags, variables, and workflows, plus `workspace_sync:sync`, `workspace:read`, `workspace:update`, `workspace:delete`, `workspace:member:read`, `workspace:member:invite`, `workspace:member:remove`, and any `action:<name>:execute` scope. An organization service account can also hold `org:read`, `org:secret:*`, `org:settings:*`, `org:workspace:read`, `workspace:create`, and `org:rbac:*`.

Neither allowlist includes the service account management scopes, so one service account can never manage another. Tracecat refuses a scope outside the allowlist with `Unsupported service account scopes requested`, and a scope you do not hold yourself with `Cannot assign service account scopes not held by the caller`.

## Availability

Service accounts require the `service_accounts` entitlement, which comes from the organization's tier. Without it the sidebar entry disappears, the page shows `Service accounts unavailable` with `Service account access is not enabled for this organization`, and a previously issued key stops authenticating.

A single-tenant self-hosted deployment has no setting that turns service accounts on.

## Related pages

* See [API authentication](/api-reference/authentication) for passing a service account API key as a bearer token in REST API requests.
* See [Custom roles and groups](/manage-platform/custom-roles) for the permission picker and custom scopes.
* See [Organization audit logs](/audit-logs/organization) for the `service_account` and `service_account_api_key` events.