Authentication

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:

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.
API — Use the API Tokens endpoint to create tokens programmatically.

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.

Using a Token

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

X-API-Key: entri_your_token_here

curl
JavaScript (fetch)
JavaScript (axios)
Python

curl https://api.nt3.io/api/projects \
  -H "X-API-Key: entri_your_token_here"

const response = await fetch("https://api.nt3.io/api/projects", {
  headers: {
    "X-API-Key": "entri_your_token_here",
  },
});
const projects = await response.json();

import axios from "axios";

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

const { data } = await client.get("/projects");

import httpx

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

with httpx.Client(base_url="https://api.nt3.io/api", headers=headers) as client:
    response = client.get("/projects")
    projects = response.json()

Using Environment Variables

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

export ENTRI_API_KEY="entri_your_token_here"

curl https://api.nt3.io/api/projects \
  -H "X-API-Key: $ENTRI_API_KEY"

const response = await fetch("https://api.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.

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

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:

{
  "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:

{
  "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.).

Overview

Endpoints

Authentication

API Tokens

Creating a Token

Using a Token

Using Environment Variables

Session Cookies (Web App Only)

What Happens if Authentication Fails

Token Best Practices

Overview

Endpoints

​API Tokens

​Creating a Token

​Using a Token

​Using Environment Variables

​Session Cookies (Web App Only)

​What Happens if Authentication Fails

​Token Best Practices

API Tokens

Creating a Token

Using a Token

Using Environment Variables

Session Cookies (Web App Only)

What Happens if Authentication Fails

Token Best Practices