Authentication & Authorization

Overview

Kape Services use JSON Web Tokens (JWT) to handle authentication and authorization of all API requests. Depending on the purpose of the request, different token types are issued, each carrying its own payload and serving a specific role in the overall flow. This design allows customers to be securely identified, their subscriptions validated, and VPN connections established in a way that respects both functionality and user anonymity.

Token Flow

The authentication process begins with the issuance of an Identity Token. This token, usually an OpenID Access Token, confirms the identity of the customer but does not contain information about subscription entitlements. Its role is purely to authenticate the user. In order to determine which features are available, the Identity Token is exchanged for a Subscription Receipt Token. This second type of token is linked to the customer’s subscription and includes the entitlement information that specifies which features the user is allowed to access. For the vast majority of API requests, the Subscription Receipt Token is the credential that must be presented.

Identity Tokens and Subscription Receipt Tokens are, however, not anonymous. Both contain references to either the user ID or the subscription ID. In cases where anonymity is crucial—specifically when establishing VPN connections—these tokens cannot be used directly. Instead, the Subscription Receipt Token must be exchanged for a Connection Authorization Token. Unlike the other tokens, the Connection Authorization Token contains no references to a particular customer. It enables the VPN server to authenticate a connection request without exposing the user’s identity, thereby providing the necessary level of privacy.

WireGuard Specifics

For Lightway VPN connections, a Connection Authorization Token is sufficient on its own. WireGuard, however, does not support token-based authentication and therefore requires a different approach. In this case, the client must generate a new public/private key pair. The public key is registered with the VPN endpoint, and the registration remains valid only for that endpoint and only for a limited period of three hours of inactivity. After that time, the registration automatically expires and a new one is required.

It is important to emphasize that a fresh key pair should be generated before every WireGuard connection. If a key pair were to be reused across multiple sessions, it would become technically possible to correlate those sessions and associate them with the same user. Such correlation would pose a risk to anonymity, as it would allow different activities to be linked back to a single identity over time. By generating a new key pair for each session, every connection remains unlinkable to previous ones, ensuring that anonymity is preserved. Beyond the privacy aspect, frequent key rotation also improves overall security by reducing the risk that a compromised key could be used over an extended period.

Conclusion

The token and credential model of Kape Services establishes a clear separation of responsibilities. Identity Tokens prove who the customer is, Subscription Receipt Tokens define which features are available, and Connection Authorization Tokens provide an anonymous credential that makes it possible to establish VPN connections without exposing user identifiers. In the case of WireGuard, anonymity and unlinkability depend on the client generating a new key pair for every single session, a practice that ensures both privacy and security at the protocol level.