> For the complete documentation index, see [llms.txt](https://docs.pretoke.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pretoke.xyz/how-it-works/wallet-login-explained.md). # Wallet Login Explained This page walks through exactly what happens, technically, when you connect your wallet — from the moment you click the button to the token that authenticates every request afterward. ## 1. The app requests a proof Before you even click "Connect," the frontend prepares a one-time random value (a "proof payload") and registers it with the TON Connect UI. This value is single-use — a fresh one is generated after every disconnect. ## 2. You approve in your wallet Your wallet app (Tonkeeper, MyTonWallet, etc.) shows a sign-in request. When you approve, your wallet uses your **private key** to sign a specific piece of data — this is called a **TON proof** — without exposing your private key to the platform at any point. The signed proof includes: * A timestamp * The domain of the site you're connecting to * The one-time payload from step 1 * The signature itself ## 3. The proof is sent to the server Your wallet address, public key, and the signed proof are sent to `POST /api/v1/auth/connect`. This is a public endpoint — you don't need to already be logged in to call it, which makes sense since this *is* how you log in. ## 4. The server verifies the signature The Auth Service performs several checks, in order: 1. **Freshness** — the proof's timestamp must be within the last 5 minutes. Older proofs are rejected (protects against someone replaying an old captured proof). 2. **Domain match** — the domain in the proof must exactly match the platform's configured domain (protects against a proof signed for a different site being replayed here). 3. **Signature verification** — the server reconstructs the exact byte sequence your wallet was supposed to sign (a standardized format: a fixed prefix, your address's workchain and hash, the domain, the timestamp, and the payload), hashes it, and verifies the ed25519 signature against the public key you provided. If any step fails, you get an authentication error and are not logged in. No blockchain transaction ever happens during this process — it's pure cryptographic signature verification, so there's no gas fee for logging in. ## 5. Your account is created or found The server looks up (or creates, on first login) a user record keyed by your wallet address. If you connected from inside Telegram, your Telegram profile info is parsed and attached at this point too. ## 6. A session token is issued The server issues a signed **JSON Web Token (JWT)** containing your wallet address and internal user ID, valid for 24 hours. A matching session record is also stored server-side, which lets the platform invalidate your session on logout even before the token's natural expiry. ## 7. The token authenticates everything else Your browser stores this token and attaches it as `Authorization: Bearer ` to every subsequent request. The API Gateway verifies the token's signature on each request — if it's valid, your wallet address and user ID are attached to the request so the right service can look up your data. If it's missing, expired, or invalid, you get a `401 Unauthorized` and the app prompts you to reconnect. ## 8. Staying logged in The app checks your token's expiry locally and quietly requests a refreshed token from the server once less than an hour remains — you never have to notice this happening. If you're gone long enough that the token fully expires, you'll simply be asked to reconnect your wallet (a quick re-approval, not a full re-registration). ## 9. Logging out Logging out invalidates your server-side session immediately (so the token can't be reused even if it hasn't technically expired yet), clears the token from your browser, and disconnects your wallet. *** For the exact wire format (request/response bodies), see [Auth API Reference](/api-reference/auth.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pretoke.xyz/how-it-works/wallet-login-explained.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.