Authentication

The documentation server uses token-based authentication to protect the upload and delete API endpoints. Without valid authentication, all uploads and deletes are rejected.

Setting Up Tokens

1. Create a Tokens File

Create a JSON file containing your API tokens:

{
  "tokens": {
    "admin": {
      "token": "your-secret-token",
      "allow_overwrite": true,
      "allow_delete": true
    },
    "ci-pipeline": {
      "token": "ABC123XYZ789",
      "projects": ["my-project", "other-project"]
    }
  }
}

The key (e.g., "admin", "ci-pipeline") is a human-readable name for the token. Each entry has:

• token (required) - the actual secret token value
• projects (optional) - list of allowed project names. Omit for all projects
• allow_overwrite (optional) - defaults to false. Set true to allow overwrites
• allow_delete (optional) - defaults to false. Set true to allow deleting versions

2. Start the Server with Tokens

Pass the tokens file using the --tokens option:

python3 -m cal_docs_server -d /path/to/docs --tokens /path/to/tokens.json

Using Tokens

Include the X-Token header in your requests:

# Upload
curl -X POST -H "X-Token: your-secret-token" \
     -F "file=@my-project-1.0.0-docs.zip" \
     http://example.com/api/upload

# Delete (requires allow_delete permission)
curl -X DELETE -H "X-Token: your-secret-token" \
     http://example.com/api/delete/my-project/1.0.0

Token Fields

Field	Type	Required	Description
token	string	yes	The actual secret token value
projects	array	no	List of allowed project names. Omit for all projects
allow_overwrite	boolean	no	Defaults to false. Set true to allow overwrites
allow_delete	boolean	no	Defaults to false. Set true to allow deleting versions
existing_projects_only	boolean	no	Defaults to false. Set true to only allow uploads to existing projects

Examples

{
  "tokens": {
    "admin": {
      "token": "your-secret-token",
      "allow_overwrite": true,
      "allow_delete": true
    },
    "ci-deploy": {
      "token": "ABC123XYZ789",
      "projects": ["my-app"]
    },
    "team-a": {
      "token": "DEF456UVW012",
      "projects": ["team-a-api", "team-a-cli", "team-a-sdk"],
      "allow_overwrite": true
    },
    "updater-only": {
      "token": "XYZ789ABC123",
      "existing_projects_only": true
    }
  }
}

Security Notes

• No tokens file = no uploads or deletes - If the server is started without --tokens, all upload and delete requests are rejected with 401 Unauthorized
• Tokens are case-sensitive - MyToken and mytoken are different tokens
• Keep tokens secret - Do not commit your tokens file to version control
• Use strong tokens - Generate random tokens with: openssl rand -hex 32
• Rotate tokens - Periodically update tokens and restart the server to apply changes
• Least privilege - Use restricted tokens for CI pipelines to limit blast radius