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

# Service Accounts

> Non-human identities with scoped tokens for programmatic API access

Service accounts are non-human identities for programmatic access to the Delphina API — for scripts, scheduled jobs, and integrations that shouldn't run under a person's login. Each service account is scoped to specific workspaces and holds one or more API tokens.

Organization admins manage service accounts at **Org Admin > Service Accounts**.

<Note>
  Service accounts are for machine-to-machine access. For your own interactive or personal automation, use a personal API token instead — see [User Settings](/user-settings).
</Note>

## When to use a service account

* The credential should belong to a team or system, not an individual, so it keeps working when people join or leave.
* You want access scoped to specific workspaces and roles, independent of any person's permissions.
* You need several tokens for the same identity (for example, one per environment) that you can rotate independently.

## Creating a service account

1. Go to **Org Admin > Service Accounts**.
2. Click **+ New service account**.
3. Enter a **Name**. This becomes a permanent identifier of the form `name@<org>.svc.delphina.ai`. Use lowercase letters, digits, and hyphens (not at the start or end), up to 64 characters.
4. Optionally add a **Description** explaining what the account is used for.
5. Click **Create**.

The name and identifier are fixed at creation and cannot be changed later. Only the description is editable afterward. A new service account has no token yet — Delphina opens its management dialog so you can create the first one.

## Assigning workspace roles

A service account can only act in workspaces you assign to it. In the account's management dialog, open the **Workspace roles** tab.

1. Select a **Workspace** and a **Role**, then click **Add**.
2. Repeat for each workspace the account needs.

Roles match the [user roles](/administration/user-management): **Developer**, **Explorer**, or **Viewer**. The token acts with the assigned role in each workspace.

### Home workspace

The **home workspace** is the workspace the account defaults to when it authenticates. Set it from the **Workspace roles** tab once at least one role is assigned. It must be one of the account's assigned workspaces.

## Managing tokens

Open the **Tokens** tab in the account's management dialog.

### Create a token

1. Click **+ Create token**.
2. Optionally give the token a **Name** to identify where it's used.
3. Choose an expiration: **No expiration**, or **7 / 30 / 90 / 180 / 365 days**.
4. Click **Create token**.

Delphina shows the full token **once**, along with a ready-to-paste `Authorization: Bearer …` header. Copy it now — for security, the token is never shown again. Afterward the list displays only a masked form (prefix + last four characters).

### Token list

Each token row shows its name, masked value, created date, last used date, and expiration. Use this to spot unused or soon-to-expire tokens.

### Revoke a token

Click the trash icon on a token row and confirm. Revocation takes effect immediately and cannot be undone — any integration using that token stops working. Revoked tokens are hidden by default; toggle **Show revoked** to see them (kept for the audit trail).

## Using a token

Send the token as a bearer credential on your API requests:

```txt theme={null}
Authorization: Bearer YOUR_TOKEN
```

The request runs as the service account, scoped to its home workspace and assigned roles. To call the Delphina MCP server with a token, see [Delphina MCP Server](/integrations/delphina-mcp).

## Deleting a service account

Click the trash icon on a service account row (or **Delete service account** in its management dialog) and confirm. Deleting an account **revokes all of its tokens immediately** and cannot be undone. Any integration using them stops working.

## Security best practices

* Give each integration its own token so you can revoke one without disrupting the others.
* Scope service accounts to the fewest workspaces and the lowest role they need.
* Set an expiration on tokens where practical, and rotate long-lived tokens periodically.
* Never commit tokens to source control. Store them in a secrets manager or environment variables.
* Revoke a token as soon as it's no longer needed or may have been exposed.