Go2Auth Developer Documentation

Go2Auth is a closed, "zero-dependency" authentication ecosystem. We do not use SDKs, third-party code, JWTs, or external authentication providers. The entire workflow operates strictly within our isolated infrastructure.

1. Initiating Authentication & Session Control

Authentication requires no complex API calls. You can integrate login and optional logout directly into your application using simple HTML links with your public API key:

<a href="https://go2auth.com/auth/login?pk=PUBLIC_API_KEY">Login</a>

<a href="https://go2auth.com/auth/logout?pk=PUBLIC_API_KEY">Logout</a>

Security Protection & Quota: API calls generating magic links are protected by a strict token rate limit against bots and spammers. Every successful webhook (both login and logout) consumes or adjusts your available quota.

2. Privacy & Data Security

Go2Auth was built with privacy as the core priority: We minimize stored personal data. Email addresses are never stored as plaintext in our database and are processed using one-way cryptographic salted hashing.

The Transit Email & Session Proxy Model: Plaintext email addresses only appear in transit during the initial authentication phase (inside the magic link and the immediate webhook payload) so your backend can map the user. Once authenticated, Go2Auth acts strictly as an auth transport layer: a 30-day secure, domain-specific HTTP-only cookie handles subsequent sessions on the client side, eliminating the need for permanent email storage.

3. The Authentication Flow

The following workflow outlines how authentication and session termination function step-by-step:

4. Webhooks & Event Handling

When a user authenticates or logs out, Go2Auth notifies your system via a POST request. Security Note: Always store your WEBHOOK_SECRET_KEY in environment variables, never hardcoded. For testing, inspection, and real-time validation of webhook payloads and endpoint configurations, we recommend utilizing Webhook.site as a dedicated diagnostics platform.

POST /your-webhook-endpoint
X-Signature: [secret_signature_value]

{
  "email": "user@domain.com",
  "action": "login/logout",
  "quota": "1499"
}

PHP

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$secret = getenv('WEBHOOK_SECRET_KEY');

$expected = hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    $data = json_decode($payload, true);
    $email = $data['email'] ?? '';
    $action = $data['action'] ?? ''; // 'login' or 'logout'
    $quota = $data['quota'] ?? 0;
    
    // Process data...
    http_response_code(200);
} else {
    http_response_code(401);
}

Node.js (Express)

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhook', express.text({type: 'application/json'}), (req, res) => {
    const signature = req.headers['x-signature'];
    const secret = process.env.WEBHOOK_SECRET_KEY;
    
    const hmac = crypto.createHmac('sha256', secret);
    const digest = hmac.update(req.body).digest('hex');

    if (signature === digest) {
        const data = JSON.parse(req.body);
        const { email, action, quota } = data; // action: 'login' or 'logout'
        res.sendStatus(200);
    } else {
        res.sendStatus(401);
    }
});

Python (Flask)

import os
from flask import Flask, request, abort
import hmac, hashlib, json

app = Flask(__name__)
WEBHOOK_SECRET = os.getenv('WEBHOOK_SECRET_KEY').encode()

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature', '')
    payload = request.get_data()
    
    expected = hmac.new(WEBHOOK_SECRET, payload, hashlib.sha256).hexdigest()
    
    if not hmac.compare_digest(expected, signature):
        abort(401)
        
    data = request.get_json()
    email = data.get("email")
    action = data.get("action")  # 'login' or 'logout'
    quota = data.get("quota")
    
    return "OK", 200

Go

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-Signature")
    
    secret := os.Getenv("WEBHOOK_SECRET_KEY")
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(expected), []byte(signature)) {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    var payload struct {
        Email  string `json:"email"`
        Action string `json:"action"` // 'login' or 'logout'
        Quota  string `json:"quota"`
    }
    json.Unmarshal(body, &payload)

    // Process payload...
    w.WriteHeader(http.StatusOK)
}

5. Closing Thoughts on Data Security

Using plain text emails strictly in transit eliminates phishing vectors by stripping away hidden tracking pixels. The design prioritizes maximum simplicity, total anonymity via database hashing, and a drastically minimized attack surface acting as a lightweight session proxy.