> ## 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.

# API Tokens

> Durable tokens for authenticating to the Nuon Control Plane API.

An **API token** authenticates requests to the [Nuon Control Plane API](/concepts/api). Use one to call the API, drive the CLI in CI/CD, or integrate Nuon into your own product.

## Token types

A token is issued against one of two identities:

* **Service account token** (the default) — the token is backed by its own [service account](/concepts/service-accounts), which carries the role you choose. The token acts as that service account and only grants access to the current org. This service account is created and managed for you. If you want a service account you manage explicitly and can mint multiple tokens for, create one directly instead.
* **Personal token** — the token is issued against your own account and uses your existing roles. It has the same access as you (including your other orgs) and stops working if your account loses access. Personal tokens have no role property.

## Token properties

| Property     | Description                                                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**     | A human-readable label to identify the token. Required.                                                                                                             |
| **Role**     | Service account tokens only. The permissions the token grants. Defaults to `org_read_only`. See [Access control](/concepts/access-control) for the available roles. |
| **Duration** | How long the token is valid. Defaults to `8760h` (one year).                                                                                                        |

Creating and managing API tokens requires **org admin** access.

## Managing tokens

You can manage tokens using both the Dashboard and the CLI. In the dashboard, go to **Settings → API tokens → Create token**.

In the CLI, use the following commands.

### Creating a token

Create a token granting access to your current org:

```sh theme={null}
nuon orgs api-tokens create --name my-token
```

By default, tokens will be read-only and expire after one year. Override these if you need admin access or a different expiration:

```sh theme={null}
nuon orgs api-tokens create --name ci-token --role org_admin --duration 720h
```

Add `--personal` to create a personal token issued against your own account instead (cannot be combined with `--role`):

```sh theme={null}
nuon orgs api-tokens create --name my-token --personal
```

<Note>
  Tokens are shown **only once** at creation time. Store the value somewhere safe (a secret manager or CI secret); you cannot retrieve it again later.
</Note>

### Listing tokens

View all active tokens in the org.

```sh theme={null}
nuon orgs api-tokens list
```

### Revoking tokens

Delete a token to revoke its access immediately.

```sh theme={null}
nuon orgs api-tokens delete --id <token-id>
```

## Using a token

To use a token, include it in API requests as a Bearer credential in the `Authorization` header:

```sh theme={null}
curl https://api.nuon.co/v1/current-user \
  -H "Authorization: Bearer <your-api-token>"
```

You can also use a token with the CLI by setting it as the value of the `NUON_API_TOKEN` environment variable or the `api_token` config value.

<CodeGroup>
  ```sh env theme={null}
  export NUON_API_TOKEN=<your-api-token>
  ```

  ```sh ~/.nuon theme={null}
  api_token: <your-api-token>
  ```
</CodeGroup>