directus-token-endpoint

Directus endpoint extension that mints access and refresh tokens for authenticated desktop sessions via a hardened /auth/mintsession route.

Overview

• Introduces a dedicated endpoint that exchanges an authenticated Directus request for a fresh access/refresh token pair.
• Persists refresh seeds in directus_sessions, mirroring core Directus semantics so existing administrative tooling continues to work.
• Guards the flow with Directus accountability checks to ensure only logged-in users can mint desktop sessions.

Features

• ✔️ Works with Directus v11+ endpoint interface.
• ✔️ Generates cryptographically strong refresh seeds (48 random bytes, Base64URL encoded).
• ✔️ Supports configurable refresh TTLs using native Directus duration strings (30m, 12h, 7d, etc.).
• ✔️ Cleans up failed refresh attempts before surfacing errors to the caller.

Requirements

• Directus ^11.0.0
• Node.js 18+ (Directus 11 baseline).
• Access to the Directus database so the endpoint can insert rows into directus_sessions.

Configuration

| Variable | Default | Description | | --- | --- | --- | | REFRESH_TOKEN_TTL | 30 days | Optional duration (e.g. 12h, 7d, 600000) that controls the lifetime of newly minted refresh tokens. Unsupported or missing values fall back to 30 days.

The duration parser accepts raw millisecond numbers or suffixed strings using one of ms, s, m, h, d, w.

Usage

Endpoint

• Route: POST /auth/mintsession
• Auth: Any valid Directus authentication method (cookie session, static token, personal access token).
• Body: None required.

Example request:

curl -X POST https://your-directus.example.com/auth/mintsession \
  -H "Authorization: Bearer <existing_access_token>"

Example success response:

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "g5H5...",
    "expiresIn": 3600,
    "issuedAt": "2025-01-01T12:00:00.000Z"
  }
}

Error responses

| HTTP | Code | When | | --- | --- | --- | | 403 | FORBIDDEN | Caller is anonymous or lacks req.accountability.user. | 500 | INTERNAL_SERVER_ERROR | Directus failed to mint access or refresh tokens after creating the session seed.

Token flow

1. Caller authenticates with any Directus-supported method.
2. /auth/mintsession writes a session row with the computed TTL to directus_sessions.
3. The Directus AuthenticationService runs refresh() with the new seed and emits access/refresh tokens plus expiry metadata.
4. On failure, the inserted session record is deleted before propagating the error.

Development

1. Clone the repo and run pnpm install.
2. Modify the source (currently the shipped entrypoint lives in dist/index.js; feel free to author a src/ structure and transpile into dist/).
3. Use pnpm pack or pnpm publish to ship updates, then bump the version in package.json.
4. Test against a local Directus instance by linking the package (pnpm link --global -> pnpm link directus-token-endpoint inside Directus) or via the manual drop-in method above.

Troubleshooting

• You must be authenticated: ensure your request includes a valid cookie or Authorization header. Personal access tokens must belong to users allowed to create sessions.
• Failed to mint desktop session tokens: usually reflects database misconfiguration or revoked Directus secrets. Check that directus_sessions is writable and the Directus instance can sign JWTs.
• Custom TTL ignored: confirm that REFRESH_TOKEN_TTL is set in the Directus runtime environment (not only in .env.example) and uses a supported suffix.

License

Released under the MIT License.