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

# Authentication

> Learn how to authenticate with the Entri API using session cookies or API tokens.

The Entri API supports two authentication methods depending on how you access it.

## Session-based authentication (web app)

When you sign in through the Entri web application, BetterAuth creates a cookie-based session. All requests made from the browser automatically include this session cookie, so no additional setup is required for web app usage.

Session authentication supports:

* Email + password sign-in
* OAuth via Google or GitHub

Sessions are managed automatically — you do not need to handle tokens or headers when using the web app.

## API token authentication (programmatic access)

For programmatic access — such as from the CLI, CI/CD pipelines, or your own integrations — use API tokens.

API tokens are passed via the `X-API-Key` request header:

```http theme={null}
GET /api/v1/projects HTTP/1.1
Host: app.nt3.io
X-API-Key: entri_your_token_here
```

All token values begin with the prefix `entri_`.

### Example: curl

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

### Example: JavaScript fetch

```javascript theme={null}
const response = await fetch('https://app.nt3.io/api/v1/projects', {
  headers: {
    'X-API-Key': process.env.ENTRI_API_TOKEN,
  },
});
const projects = await response.json();
```

### Example: CLI

The CLI handles token storage and injection automatically. After running `nt3 login`, the token is stored locally and attached to every outgoing request:

```bash theme={null}
nt3 login -t entri_your_token_here
nt3 push  # token is sent automatically
```

You can also set the token via 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
```

## Token priority order

When the CLI determines which token to use, it checks sources in this order:

1. `NT3_API_TOKEN` environment variable (highest priority)
2. `.nt3.local.json` in the current directory (folder-scoped)
3. `~/.nt3/config.json` (global)

This allows you to override credentials per project or per CI environment without modifying the global config.

## Security recommendations

* Never commit API tokens to source control
* Store tokens in environment variables or a secrets manager in CI/CD
* Use short-lived or project-scoped tokens where possible
* Run `nt3 status` to confirm which token is currently active

<Note>
  The GraphQL API at `/graphql` also supports API token authentication via the same `X-API-Key` header.
</Note>