The datasette-auth-tokens plugin is an authentication extension for Datasette that enables secure API key-based access through query string parameters. This plugin facilitates integration between protected Datasette instances and external applications that require public-only access methods, such as Google Sheets' IMPORTDATA() function.

The datasette-auth-tokens plugin addresses a critical accessibility challenge in Datasette deployments: enabling external applications to access protected data sources without exposing full database credentials or requiring complex OAuth flows. By implementing token-based authentication via query string parameters, the plugin allows clients like Google Sheets to authenticate against secured Datasette instances using simple HTTP requests ¹⁾.

Datasette, a tool for exploring and publishing data, typically restricts access to sensitive databases. The plugin bridges the gap between Datasette's security model and the limitations of spreadsheet applications that support only straightforward URL-based data retrieval methods ²⁾.

The plugin operates by intercepting HTTP requests to Datasette and validating authentication tokens passed as query string parameters. Rather than requiring users to include credentials directly in URLs—a significant security anti-pattern—the plugin implements a token validation layer that maps ephemeral or long-lived API keys to specific database permissions.

When a client application initiates a request to a protected Datasette instance, it appends an authentication token as a URL parameter. The plugin validates this token against a configured token store, which may include token metadata such as expiration dates, scope limitations, and associated user or service identities ³⁾.

The architecture supports multiple authentication strategies: - Static tokens: Long-lived API keys suitable for service-to-service communication - Scoped tokens: Keys restricted to specific datasets, tables, or SQL queries - Time-limited tokens: Temporary credentials that expire after a specified duration

The primary use case involves connecting Google Sheets to protected Datasette instances using the IMPORTDATA() function. Google Sheets can only execute unauthenticated HTTP requests or requests with credentials passed as URL parameters; the plugin enables the latter approach securely by allowing tokens rather than passwords in query strings ⁴⁾.

Additional applications include: - Data visualization tools: Connecting Tableau, Grafana, or other BI platforms to Datasette without exposing administrative credentials - Automated reporting: Enabling scheduled tasks and ETL pipelines to fetch current data from protected instances - Cross-organizational data sharing: Issuing time-limited tokens to external partners for read-only access to specific datasets - Mobile applications: Providing mobile clients with bearer tokens for API authentication

Token-based authentication via query strings presents distinct security trade-offs. While preferable to embedding passwords in URLs, query string parameters are logged in server access logs, browser history, and proxies. Organizations implementing datasette-auth-tokens should enforce additional security measures:

- HTTPS enforcement: All requests must traverse encrypted channels to prevent token interception - Token rotation: Regular replacement of long-lived tokens limits exposure window if tokens are compromised - Audit logging: Tracking which tokens accessed which resources and when - Rate limiting: Preventing brute-force token discovery attacks - Scope narrowing: Issuing tokens with minimal necessary permissions for each use case

The plugin integrates with Datasette's existing permission model, which controls which tables, databases, and operations each authenticated user or token can perform ⁵⁾.

The datasette-auth-tokens plugin operates within Datasette's plugin architecture, which allows extensions to hook into authentication, request processing, and response handling. The plugin leverages Datasette's built-in permission checking mechanisms to enforce fine-grained access control ⁶⁾.

Configuration typically involves registering token definitions in Datasette's metadata.json file or through environment variables, allowing operators to manage credentials without modifying application code. This approach aligns with twelve-factor application principles for configuration management.

The plugin enables practical integration between Datasette and external applications with limited authentication capabilities. By abstracting token management and validation, datasette-auth-tokens provides a safer alternative to naive credential handling while maintaining compatibility with simple client applications that cannot implement standard OAuth or API key header patterns.

• Datasette JSON API
• Query Parameter vs Header-Based Authentication
• Datasette and Data Tools
• latest.datasette.io