Skip to main content
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. 
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 -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 -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 -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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us