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

# Service Accounts

> Named machine identities for automation, CI/CD.

A **service account** is a named machine identity in your Nuon org. Use service accounts for automation, CI/CD pipelines, and any integration that calls the Nuon API on behalf of a system rather than a person.

Unlike a one-off [API token](/concepts/api-tokens), a service account is a persistent identity you manage. You can rename it, change its role, and mint (or invalidate) multiple tokens for it over time.

Managing service accounts requires **org admin** access.

## Roles

Every service account is assigned exactly one role, which determines its permissions. Roles are org-scoped. There are currently two roles, with more planned soon.

| Role            | Title     | Description                  |
| --------------- | --------- | ---------------------------- |
| `org_admin`     | Admin     | Full access to the org.      |
| `org_read_only` | Read-only | Read-only access to the org. |

You can list available roles using the CLI.

```sh theme={null}
nuon roles list
```

## Managing service accounts

Service accounts can be managed in the Dashboard on the **Service accounts** page, and with the CLI `service-accounts` commands.

### Create

Create a new service account. Both a name and a role are required.

```sh theme={null}
nuon service-accounts create --name ci --role org_read_only
```

### Mint a token

Create a token for a service account. The duration will default to one year.

```sh theme={null}
nuon service-accounts tokens create --id <account-id>
```

Optionally set a custom duration.

```sh theme={null}
nuon service-accounts tokens create --id <account-id> --duration 720h
```

<Warning>
  The token value is shown **only once**. Copy it immediately into your secret manager or CI secret store — you cannot retrieve it again.
</Warning>

### Update a service account

You can change a service account's name or role.

```sh theme={null}
nuon service-accounts update-name --id <account-id> --name new-name
```

```sh theme={null}
nuon service-accounts update-role --id <account-id> --role org_admin
```

A service account can only have one role at a time. Updating the role will replace the service account's current role.

### List

List active service accounts.

```sh theme={null}
nuon service-accounts list
```

### Delete

Deleting a service account will remove its roles and invalidate all of its tokens.

```sh theme={null}
nuon service-accounts delete --id <account-id>
```

## Runner service accounts

Every runner is backed by its own machine identity — a service account with the special `runner` role. This is an implementation detail you can mostly ignore. You do not need to create or manage these service accounts yourself.

Because they're managed for you, runner service accounts are hidden from `nuon service-accounts list` by default, but you can see them with the `--include-runners` flag.

```sh theme={null}
nuon service-accounts list --include-runners
```