API Tokens - Entri

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.

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.

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

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:

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

curl https://app.nt3.io/api/organizations/org_789xyz/tokens \
  -H "Cookie: session=..."

Response:

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

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:

Create a new token

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"}'

Update your secrets

Update the token value in your CI/CD secrets, environment variables, or secrets manager with the new value.

Revoke the old token

Once the new token is in place and working, revoke the old one:

curl -X DELETE https://app.nt3.io/api/organizations/org_789xyz/tokens/tok_old_id \
  -H "Cookie: session=..."

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.

​Endpoints

​Create a Token

​List Tokens

​Revoke a Token

​Token Expiration

​Token Rotation

​Key Notes

Endpoints

Create a Token

List Tokens

Revoke a Token

Token Expiration

Token Rotation

Key Notes