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

> Authenticate API requests using API tokens or session cookies.

The Entri API supports two authentication methods. For all programmatic access — scripts, CI/CD pipelines, integrations, and the CLI — use an **API token**. The session cookie method is used internally by the Entri web application and is not recommended for external clients.

## API Tokens

API tokens are long-lived credentials scoped to your organization. Every token starts with the prefix `entri_` so they are easy to identify in logs and environment variables.

### Creating a Token

Tokens can be created in two ways:

1. **Web app** — Navigate to your organization settings, open the API Tokens section, and click "Create token". Give the token a descriptive name so you remember what it is used for. The full token value is shown only once at creation time.

2. **API** — Use the [API Tokens endpoint](/api-reference/endpoints/api-tokens) to create tokens programmatically.

<Warning>
  Store your token securely. Treat it like a password. If a token is compromised, revoke it immediately from organization settings and create a new one.
</Warning>

### Using a Token

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

```
X-API-Key: entri_your_token_here
```

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

  <Tab title="JavaScript (fetch)">
    ```javascript theme={null}
    const response = await fetch("https://app.nt3.io/api/projects", {
      headers: {
        "X-API-Key": "entri_your_token_here",
      },
    });
    const projects = await response.json();
    ```
  </Tab>

  <Tab title="JavaScript (axios)">
    ```javascript theme={null}
    import axios from "axios";

    const client = axios.create({
      baseURL: "https://app.nt3.io/api",
      headers: {
        "X-API-Key": "entri_your_token_here",
      },
    });

    const { data } = await client.get("/projects");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import httpx

    headers = {"X-API-Key": "entri_your_token_here"}

    with httpx.Client(base_url="https://app.nt3.io/api", headers=headers) as client:
        response = client.get("/projects")
        projects = response.json()
    ```
  </Tab>
</Tabs>

### Using Environment Variables

Never hard-code tokens in source code. Use an environment variable instead:

```bash theme={null}
export ENTRI_API_KEY="entri_your_token_here"
```

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

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

## Session Cookies (Web App Only)

The Entri web application authenticates via session cookies managed by BetterAuth. When you sign in through the browser, a secure HTTP-only cookie is set automatically and included on every subsequent request.

<Info>
  Session authentication is intended for browser-based usage only. If you are building an integration or automation, use an API token instead.
</Info>

## What Happens if Authentication Fails

If no credentials are provided, or if the provided token is invalid or revoked, the API returns a `401 Unauthorized` response:

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}
```

If valid credentials are provided but the token does not have permission to perform the requested action, the API returns a `403 Forbidden` response:

```json theme={null}
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}
```

## Token Best Practices

* Create a separate token for each integration or service that calls the API. This makes it easy to revoke access for one consumer without affecting others.
* Rotate tokens periodically as part of your security hygiene.
* Never commit tokens to version control. Use a secrets manager or environment variable.
* For CI/CD pipelines, use your provider's secrets mechanism (GitHub Actions secrets, GitLab CI variables, etc.).