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

> Create and revoke API tokens programmatically.

**API tokens** are long-lived credentials used to authenticate programmatic access to the Entri REST API. Every token is prefixed with `entri_` and is scoped to an organization or a specific project.

You can manage tokens from the Entri web app (organization settings), or programmatically through the API token endpoints documented here. Programmatic management is useful for automated credential rotation, onboarding scripts, or CI/CD bootstrap pipelines.

<Warning>
  The full token value is only returned once — at creation time. After that, the token hash is never exposed. Treat tokens like passwords and store them in a secrets manager.
</Warning>

## Endpoints

**Organization-level tokens**

```
POST   /api/organizations/:orgId/tokens              Create a token
GET    /api/organizations/:orgId/tokens              List tokens
DELETE /api/organizations/:orgId/tokens/:tokenId     Revoke a token
```

**Project-level tokens**

```
POST   /api/projects/:projectId/tokens              Create a project token
GET    /api/projects/:projectId/tokens              List project tokens
DELETE /api/projects/:projectId/tokens/:tokenId     Revoke a project token
```

## Create a Token

```bash theme={null}
curl -X POST https://app.nt3.io/api/organizations/org_789xyz/tokens \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Actions — main repo",
    "scopes": ["translations:read", "translations:write"],
    "expiresAt": "2026-01-01T00:00:00.000Z"
  }'
```

**Request body:**

| Field       | Type      | Required | Description                                                             |
| ----------- | --------- | -------- | ----------------------------------------------------------------------- |
| `name`      | string    | Yes      | Descriptive label for the token.                                        |
| `scopes`    | string\[] | No       | Permission scopes for this token.                                       |
| `expiresAt` | string    | No       | ISO 8601 datetime after which the token is invalid. Omit for no expiry. |

**Response:**

```json theme={null}
{
  "_id": "tok_abc123",
  "name": "GitHub Actions — main repo",
  "token": "entri_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "organizationId": "org_789xyz",
  "scopes": ["translations:read", "translations:write"],
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "created": "2025-03-01T10:00:00.000Z"
}
```

The `token` field contains the full token value. Copy it now — it will not be shown again.

## List Tokens

Returns all active tokens for the organization. The full token value is never returned in list responses:

```bash theme={null}
curl https://app.nt3.io/api/organizations/org_789xyz/tokens \
  -H "Cookie: session=..."
```

**Response:**

```json theme={null}
[
  {
    "_id": "tok_abc123",
    "name": "GitHub Actions — main repo",
    "organizationId": "org_789xyz",
    "scopes": ["translations:read", "translations:write"],
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "lastUsedAt": "2025-03-02T08:45:00.000Z",
    "created": "2025-03-01T10:00:00.000Z"
  },
  {
    "_id": "tok_def456",
    "name": "Staging deploy pipeline",
    "organizationId": "org_789xyz",
    "scopes": null,
    "expiresAt": null,
    "lastUsedAt": null,
    "created": "2025-02-20T15:00:00.000Z"
  }
]
```

## Revoke a Token

Revoking a token immediately invalidates it. Any in-flight requests using the token will fail with `401 Unauthorized`:

```bash theme={null}
curl -X DELETE https://app.nt3.io/api/organizations/org_789xyz/tokens/tok_abc123 \
  -H "Cookie: session=..."
```

## Token Expiration

Tokens can optionally expire. Set `expiresAt` to an ISO 8601 datetime when creating a token. After that date, the token is automatically rejected with a `401 Unauthorized` response, even if it has not been explicitly revoked.

Tokens without an `expiresAt` value never expire automatically. Rotate them manually as part of your security hygiene.

## Token Rotation

To rotate a token without downtime:

<Steps>
  <Step title="Create a new token">
    ```bash theme={null}
    curl -X POST https://app.nt3.io/api/organizations/org_789xyz/tokens \
      -H "Cookie: session=..." \
      -H "Content-Type: application/json" \
      -d '{"name": "GitHub Actions — rotated 2025-03"}'
    ```
  </Step>

  <Step title="Update your secrets">
    Update the token value in your CI/CD secrets, environment variables, or secrets manager with the new value.
  </Step>

  <Step title="Revoke the old token">
    Once the new token is in place and working, revoke the old one:

    ```bash theme={null}
    curl -X DELETE https://app.nt3.io/api/organizations/org_789xyz/tokens/tok_old_id \
      -H "Cookie: session=..."
    ```
  </Step>
</Steps>

## Key Notes

* Give each token a descriptive name that identifies its purpose and the system using it. This makes it easy to understand which token to revoke if one is compromised.
* The `lastUsedAt` field helps identify stale tokens that can be safely revoked.
* Use `expiresAt` to enforce automatic expiry for short-lived automation credentials.