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

# API Tokens

> Generate and manage API tokens for programmatic access to Entri.

API tokens let you authenticate with the Entri API from the CLI, CI/CD pipelines, and any custom integrations without using your account password.

## Creating a Token

<Steps>
  <Step title="Open API Tokens settings">
    Go to the Entri dashboard and navigate to **Settings > API Tokens**.
  </Step>

  <Step title="Create a new token">
    Click **Create token**. Give the token a descriptive name that identifies where it will be used (e.g., `GitHub Actions`, `Local dev`, `Staging server`). Optionally set an expiry date.
  </Step>

  <Step title="Copy the token">
    The token is shown **once** immediately after creation. Copy it and store it in a safe place — it cannot be retrieved again. If you lose it, revoke the token and create a new one.
  </Step>
</Steps>

All API tokens start with the prefix `entri_`.

## Token Expiration

When creating a token, you can optionally set an `expiresAt` date. After that date, the token is automatically rejected even if it has not been explicitly revoked. Tokens without an expiry date remain valid until revoked.

Use expiring tokens for short-lived automation credentials (e.g., CI/CD jobs, deploy scripts) and non-expiring tokens for long-lived integrations.

## Using a token

Pass the token in the `X-API-Key` header on every request:

```http theme={null}
X-API-Key: entri_your_token_here
```

### With the CLI

```bash theme={null}
nt3 login -t entri_your_token_here
```

### With curl

```bash theme={null}
curl https://app.nt3.io/api/v1/projects \
  -H "X-API-Key: entri_your_token_here"
```

### With an environment variable

The CLI also reads the `NT3_API_TOKEN` environment variable, which takes priority over stored credentials:

```bash theme={null}
export NT3_API_TOKEN=entri_your_token_here
nt3 push
```

This is the recommended approach for CI/CD environments.

## Managing Tokens

All tokens are listed on the **Settings > API Tokens** page. From there you can:

* View the token name, creation date, and optional expiry
* See when the token was last used
* Revoke any token to immediately invalidate access

Revoking a token is permanent. Any system using the revoked token will immediately receive `401 Unauthorized` responses.

Tokens can also be managed via the API — see the [API Tokens reference](/api-reference/endpoints/api-tokens) for programmatic management using endpoints at `/api/organizations/:orgId/tokens`.

## Security best practices

**Do not commit tokens to source control.** Even in private repositories, tokens should be kept out of code and configuration files that are checked in.

**Use environment variables or a secrets manager.** Store tokens in:

* CI/CD secrets (GitHub Actions secrets, GitLab CI variables, etc.)
* A secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler, etc.)
* Your local shell profile for development (with appropriate file permissions)

**Use one token per environment.** Create separate tokens for local development, staging, and production. This makes it easier to rotate credentials without affecting other environments.

**Rotate tokens periodically.** Delete old tokens and create new ones on a regular schedule, or whenever a team member with access leaves.

**Audit token usage.** The last-used timestamp on the token list helps you identify tokens that are no longer in use. Delete unused tokens.

<Warning>
  If you suspect a token has been compromised, delete it immediately from **Settings > API Tokens**. Access is revoked the moment the token is deleted.
</Warning>

## Token format

All tokens follow this format:

```
entri_<random_string>
```

The CLI validates this format when you run `nt3 login` — it rejects any value that does not start with `entri_`.