Authentication

Secure your DeepLX instance with token authentication

DeepLX supports optional token-based authentication to protect your translation API from unauthorized access. When enabled, all requests to translation endpoints must include a valid access token.

Enabling Authentication

Authentication is controlled by the TOKEN configuration option. If no token is set, the API is publicly accessible.

Environment Variable

export TOKEN="your-secret-token-here"
./deeplx

When a token is configured, DeepLX will print “Access token is set.” during startup.

How Authentication Works

The authentication middleware (authMiddleware in service/service.go:29-61) validates tokens on all protected endpoints:

• /translate (Free API)
• /v1/translate (Pro API)
• /v2/translate (Official format compatible API)

Token Validation Process

1. If TOKEN is not configured, all requests are allowed
2. If TOKEN is configured, the middleware checks for the token in two locations:
   • Query parameter: ?token=xxx
   • Authorization header: Authorization: Bearer xxx or Authorization: DeepL-Auth-Key xxx
3. If neither matches the configured token, a 401 Unauthorized response is returned

Client Authentication Methods

Method 1: Query Parameter

Append the token as a query parameter to the request URL.

cURL

curl -X POST "http://localhost:1188/translate?token=your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!",
    "source_lang": "EN",
    "target_lang": "ZH"
  }'

Method 2: Bearer Token Header

Include the token in the Authorization header using the Bearer token format.

cURL

curl -X POST "http://localhost:1188/translate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token-here" \
  -d '{
    "text": "Hello, world!",
    "source_lang": "EN",
    "target_lang": "ZH"
  }'

Method 3: DeepL-Auth-Key Header

For compatibility with DeepL’s official API format, you can use the DeepL-Auth-Key prefix instead of Bearer.

cURL

curl -X POST "http://localhost:1188/translate" \
  -H "Content-Type: application/json" \
  -H "Authorization: DeepL-Auth-Key your-secret-token-here" \
  -d '{
    "text": "Hello, world!",
    "source_lang": "EN",
    "target_lang": "ZH"
  }'

Authorization Header Format

The middleware supports two header formats:

1. Bearer token: Authorization: Bearer <token>
2. DeepL Auth Key: Authorization: DeepL-Auth-Key <token>

The header must contain exactly two space-separated parts. The first part must be either Bearer or DeepL-Auth-Key, followed by the token.

Invalid formats that will be rejected:

• Authorization: your-token (missing prefix)
• Authorization: InvalidPrefix your-token (invalid prefix)
• Authorization: Bearer token with spaces (too many parts)

Unauthorized Response

If authentication fails, the API returns a 401 Unauthorized response:

{
  "code": 401,
  "message": "Invalid access token"
}

Security Best Practices

Important security recommendations:

1. Use strong tokens: Generate cryptographically secure random tokens
2. Keep tokens secret: Never commit tokens to version control
3. Use HTTPS: Always deploy with TLS/SSL in production to prevent token interception
4. Rotate tokens: Periodically change your access token
5. Restrict network access: Use firewall rules or reverse proxy to limit who can reach your instance

Generating Secure Tokens

OpenSSL

# Generate a random 32-byte token
openssl rand -hex 32

Disabling Authentication

To disable authentication, simply don’t set the TOKEN configuration:

# No authentication - API is publicly accessible
./deeplx -ip 0.0.0.0 -port 1188

Running without authentication on a public network exposes your instance to abuse. Only do this in trusted environments or behind additional authentication layers.