API Security: Guest Vs. Authenticated Endpoint Separation

In the ever-evolving landscape of web applications and APIs, security and clarity are paramount. When building services that handle sensitive information, like the one-time secret functionality offered by OneTimeSecret, it's crucial to implement a robust security architecture. A key aspect of this architecture involves clearly delineating access levels for different user types. This article delves into the importance of separating API endpoints for guest (anonymous) users versus authenticated users, a strategy that significantly enhances security, simplifies management, and improves the overall developer experience.

The Power of Distinct API Routes for Enhanced Security

Distinct API routes are fundamental to building secure and scalable applications. By creating separate, non-overlapping API paths for guest and authenticated access, we can achieve a level of control and clarity that is simply not possible when mixing authentication requirements. Currently, some routes might use flags like allow_anonymous: true to serve both types of users. While this might seem convenient, it introduces ambiguity and complexity. The proposed architectural change, which involves introducing distinct routes such as /api/v2/guest/* for anonymous operations and keeping authenticated operations at /api/v2/* (or similar structures for v3), addresses this head-on. This separation is not just about tidiness; it's a strategic move to bolster security. It directly enables features like restricting secret creation to authenticated users (as mentioned in issue #1531) and opens up significant possibilities for network security controls. Imagine being able to apply different firewall rules, Web Application Firewall (WAF) policies, or rate-limiting strategies specifically to guest endpoints, while restricting authenticated endpoints to a more secure network, like a VPN. This granular control is a game-changer for protecting your service and your users' data.

Why Separate Routes Are a Security Game-Changer

The motivation behind adopting separate API routes for guest and authenticated access is multi-faceted, each point reinforcing the others to create a stronger, more maintainable system. Firstly, and perhaps most critically, this separation directly enables tighter security controls, such as the ability to disable guest routes entirely. This makes implementing features like restricting secret creation solely to authenticated users (issue #1531) a trivial matter of configuration. You gain the power to control who can perform sensitive actions, significantly reducing the attack surface. Secondly, from a network and infrastructure perspective, distinct routes are invaluable. They allow for sophisticated firewall and network-level access controls. You can implement aggressive rate-limiting on public-facing guest endpoints to prevent abuse, while ensuring that authenticated endpoints are only accessible from trusted networks, perhaps via a VPN. This tiered security approach is essential for protecting against various forms of cyber threats. Thirdly, this approach promotes a single-purpose design for each route. When a route is designed with a clear authentication requirement in mind, it eliminates the need for conditional branching logic within the controller, simplifying the code and reducing the potential for bugs. This leads to cleaner, more predictable behavior. Fourthly, the clarity provided by the URL structure itself is a significant benefit. A URL like /api/v2/guest/secret/conceal immediately tells you that this operation does not require authentication. Conversely, /api/v2/secret/:key implies that authentication is necessary. This immediate understanding is crucial for developers integrating with your API, reducing confusion and potential misuse. Finally, this clear separation greatest API documentation. When documentation is unambiguous about the authentication requirements for each endpoint, it empowers developers to use the API correctly and securely from the outset. It removes guesswork and streamlines the integration process, making your API more accessible and user-friendly. In essence, separating API routes for guest and authenticated access is not just an architectural choice; it's a foundational pillar for building a secure, scalable, and maintainable API service.

Navigating the New API Landscape: v2 and v3 Structures

To illustrate how this separation can be implemented, let's look at the proposed route structures for both the v2 API (branching from main for v0.23.2) and the v3 API (branching from develop). This provides a clear roadmap for implementation and demonstrates the consistency across API versions.

v2 API: A Foundation for Secure Access

In the v2 API, we introduce a clear prefix for guest operations: /api/v2/guest/*. These routes are designed to be accessible without any authentication, catering to users who might not have an account or who need to perform certain actions anonymously. This includes operations like creating a secret anonymously (POST /api/v2/guest/secret/conceal), generating a random secret (POST /api/v2/guest/secret/generate), viewing secret information (GET /api/v2/guest/secret/:key), revealing the secret content (POST /api/v2/guest/secret/:key/reveal), burning a secret via its receipt (POST /api/v2/guest/receipt/:key/burn), and viewing receipt metadata (GET /api/v2/guest/receipt/:key). The explicit /guest/ prefix makes the intent of these routes unmistakable.

In parallel, the authenticated routes remain accessible under the root /api/v2/* path. These routes explicitly require session or API key authentication. They mirror the functionality of the guest routes but are tied to an authenticated user's session or credentials. This includes creating secrets with ownership (POST /api/v2/secret/conceal), generating random secrets (POST /api/v2/secret/generate), viewing secret info (GET /api/v2/secret/:key), revealing secret content (POST /api/v2/secret/:key/reveal), burning secrets via receipts (POST /api/v2/receipt/:key/burn), viewing receipt metadata (GET /api/v2/receipt/:key), and importantly, listing a user's recent receipts (GET /api/v2/receipt/recent). By enforcing authentication for these routes, we ensure that actions like viewing recent receipts are tied to a specific user's context, enhancing privacy and security. The critical takeaway here is that existing authenticated routes will now actively reject anonymous requests, ensuring that the separation is strictly enforced.

v3 API: Modernization with Clearer Paths

Moving to the v3 API, the principles remain the same, but the naming conventions are slightly adjusted to align with modern API design practices. For guest routes, we propose the prefix /api/v3/share/*. This prefix, similar to /guest/, clearly signifies that these endpoints are intended for public or anonymous access. The functionality mirrored from v2 includes creating secrets anonymously (POST /api/v3/share/secret), generating random secrets (POST /api/v3/share/secret/generate), viewing secret information (GET /api/v3/share/secret/:key), revealing secret content (POST /api/v3/share/secret/:key/reveal), burning secrets via receipts (POST /api/v3/share/receipt/:key/burn), and viewing receipt metadata (GET /api/v3/share/receipt/:key). This explicit naming convention makes it easy for developers to understand the access requirements at a glance.

For authenticated operations in v3, the routes are placed directly under the /api/v3/* root. This convention implies that authentication is a prerequisite for accessing these endpoints. The authenticated routes include creating secrets with ownership (POST /api/v3/secret), generating random secrets (POST /api/v3/secret/generate), viewing secret information (GET /api/v3/secret/:key), revealing secret content (POST /api/v3/secret/:key/reveal), burning secrets via receipts (POST /api/v3/receipt/:key/burn), viewing receipt metadata (GET /api/v3/receipt/:key), and listing a user's recent receipts (GET /api/v3/receipt/recent). The v3 API aims for a modern RESTful design, and this endpoint structure aligns perfectly with those goals. The consistency in the authentication enforcement pattern between v2 and v3 ensures a smoother transition for developers familiar with either version and reinforces the overall security strategy of the platform. This clear demarcation ensures that anonymous users can't accidentally access authenticated resources, and authenticated users have a clear path to all their associated functionalities.

Choosing the Right Naming Convention: A Deliberate Decision

When designing an API, the naming of endpoints is more than just a stylistic choice; it's a critical part of the user experience and the overall clarity of the system. We considered several naming alternatives for our guest and authenticated routes to ensure we arrived at the most intuitive and effective structure. Each option presented a slightly different philosophy, and evaluating them helped us solidify our recommendation.

Option A, which is our proposed approach, uses a specific prefix for guest routes – /guest/ in v2 and /share/ in v3. The authenticated routes, on the other hand, remain at the root of their respective API versions (e.g., /api/v2/* or /api/v3/*). The logic here is that the guest routes are explicitly marked, making them stand out and clearly indicating that they do not require authentication. The authenticated routes are considered the default or