# ๐ŸŒ GAuth-Central API Endpoints ## Base URL ``` Local Development: http://localhost:8080 Production: http://your-domain.com ``` ## API Version: v1 Base Path: `/v1` --- ## ๐Ÿ“ Endpoints ### Public Endpoints (No Authentication Required) #### 1. Homepage ``` GET / Content-Type: text/html ``` **Response:** HTML homepage --- #### 2. Swagger Documentation ``` GET /docs/index.html Content-Type: text/html ``` **Response:** Swagger UI --- ### Authentication Endpoints #### 3. Register User ``` POST /v1/auth/register Content-Type: application/json Rate Limit: 3 requests / 5 minutes ``` **Request Body:** ```json { "email": "user@example.com", "password": "SecurePass123!", "user_name": "username" } ``` **Response (201):** ```json { "message": "User created successfully. Please verify your email.", "user": { "id": "uuid", "email": "user@example.com", "user_name": "username" } } ``` **cURL Example:** ```bash curl -X POST http://localhost:8080/v1/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "password": "SecurePass123!", "user_name": "username" }' ``` --- #### 4. Login ``` POST /v1/auth/login Content-Type: application/json Rate Limit: 5 requests / 1 minute ``` **Request Body:** ```json { "email": "user@example.com", "password": "SecurePass123!" } ``` **Response (200):** ```json { "access_token": "eyJhbGciOiJIUzI1NiIs...", "refresh_token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "uuid", "email": "user@example.com", "user_name": "username" } } ``` **cURL Example:** ```bash curl -X POST http://localhost:8080/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "password": "SecurePass123!" }' ``` --- #### 5. Email Verification ``` GET /v1/auth/verify-email?token={verification_token} ``` **Query Parameters:** - `token` (required): Email verification token **Response (200):** ```json { "message": "Email verified successfully" } ``` **cURL Example:** ```bash curl -X GET "http://localhost:8080/v1/auth/verify-email?token=abc123xyz" ``` --- #### 6. OAuth Login (Google/GitHub) ``` GET /v1/auth/{provider} ``` **Parameters:** - `provider`: `google` or `github` **Example:** ``` http://localhost:8080/v1/auth/google http://localhost:8080/v1/auth/github ``` **Response:** Redirects to OAuth provider --- #### 7. OAuth Callback ``` GET /v1/auth/{provider}/callback ``` **Parameters:** - `provider`: `google` or `github` **Query Parameters:** (Provided by OAuth provider) - `code` - `state` **Response (200):** ```json { "access_token": "eyJhbGciOiJIUzI1NiIs...", "refresh_token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "uuid", "email": "user@example.com", "user_name": "username" } } ``` --- #### 8. Refresh Token ``` POST /v1/auth/refresh Content-Type: application/json ``` **Request Body:** ```json { "refresh_token": "eyJhbGciOiJIUzI1NiIs..." } ``` **Response (200):** ```json { "access_token": "eyJhbGciOiJIUzI1NiIs...", "refresh_token": "eyJhbGciOiJIUzI1NiIs..." } ``` **cURL Example:** ```bash curl -X POST http://localhost:8080/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{ "refresh_token": "your_refresh_token_here" }' ``` --- ### Protected Endpoints (Authentication Required) **Note:** All protected endpoints require the `Authorization` header: ``` Authorization: Bearer {access_token} ``` --- #### 9. Get Current User ``` GET /v1/auth/me Authorization: Bearer {access_token} ``` **Response (200):** ```json { "id": "uuid", "email": "user@example.com", "user_name": "username", "email_verified": true, "created_at": "2026-02-04T00:00:00Z" } ``` **cURL Example:** ```bash curl -X GET http://localhost:8080/v1/auth/me \ -H "Authorization: Bearer your_access_token_here" ``` --- #### 10. Validate Token ``` GET /v1/auth/validate Authorization: Bearer {access_token} ``` **Response (200):** ```json { "message": "Token is valid", "user_id": "uuid", "email": "user@example.com" } ``` **cURL Example:** ```bash curl -X GET http://localhost:8080/v1/auth/validate \ -H "Authorization: Bearer your_access_token_here" ``` --- ## ๐Ÿ”’ Authentication Flow ### Standard Email/Password Flow ``` 1. Register POST /v1/auth/register โ†“ 2. Verify Email GET /v1/auth/verify-email?token=... โ†“ 3. Login POST /v1/auth/login โ†“ 4. Access Protected Resources GET /v1/auth/me (with Bearer token) ``` ### OAuth Flow ``` 1. Initiate OAuth GET /v1/auth/google (or /github) โ†“ 2. User authorizes on OAuth provider โ†“ 3. Callback with code GET /v1/auth/google/callback?code=... โ†“ 4. Access Protected Resources GET /v1/auth/me (with Bearer token) ``` --- ## ๐Ÿ“ Error Responses ### Standard Error Format ```json { "error": "Error message description" } ``` ### Common Error Codes | Status Code | Meaning | |------------|---------| | 400 | Bad Request - Invalid input | | 401 | Unauthorized - Invalid or missing token | | 403 | Forbidden - Valid token but insufficient permissions | | 404 | Not Found - Resource not found | | 429 | Too Many Requests - Rate limit exceeded | | 500 | Internal Server Error | --- ## ๐Ÿšฆ Rate Limits | Endpoint | Limit | Time Window | |----------|-------|-------------| | POST /v1/auth/register | 3 requests | 5 minutes | | POST /v1/auth/login | 5 requests | 1 minute | | All API endpoints | 100 requests | 1 minute | **Rate Limit Headers:** ``` X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1643980800 ``` --- ## ๐Ÿ”‘ Authentication Headers ### Access Token ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### CORS Headers ``` Origin: http://localhost:3000 Content-Type: application/json ``` --- ## ๐ŸŒ CORS Configuration **Allowed Origins:** - `http://localhost:3000` (development) **Allowed Methods:** - GET, POST, PUT, PATCH, DELETE, OPTIONS **Allowed Headers:** - Origin, Content-Type, Accept, Authorization **Credentials:** - Enabled (`Access-Control-Allow-Credentials: true`) --- ## ๐Ÿ“ฆ Response Examples ### Successful Response ```json { "message": "Operation successful", "data": { ... } } ``` ### Error Response ```json { "error": "Invalid credentials" } ``` ### Validation Error ```json { "error": "Validation failed: email is required" } ``` --- ## ๐Ÿ”— Frontend Integration ### JavaScript/TypeScript Example ```javascript // Base URL const API_BASE_URL = 'http://localhost:8080'; // Login async function login(email, password) { const response = await fetch(`${API_BASE_URL}/v1/auth/login`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, credentials: 'include', body: JSON.stringify({ email, password }) }); const data = await response.json(); if (response.ok) { localStorage.setItem('access_token', data.access_token); localStorage.setItem('refresh_token', data.refresh_token); return data; } else { throw new Error(data.error); } } // Get Current User (Protected) async function getCurrentUser() { const token = localStorage.getItem('access_token'); const response = await fetch(`${API_BASE_URL}/v1/auth/me`, { method: 'GET', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', }, credentials: 'include' }); const data = await response.json(); if (response.ok) { return data; } else { throw new Error(data.error); } } // Register async function register(email, password, username) { const response = await fetch(`${API_BASE_URL}/v1/auth/register`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, credentials: 'include', body: JSON.stringify({ email, password, user_name: username }) }); const data = await response.json(); if (!response.ok) { throw new Error(data.error); } return data; } ``` ### Axios Example ```javascript import axios from 'axios'; const api = axios.create({ baseURL: 'http://localhost:8080/v1', withCredentials: true, headers: { 'Content-Type': 'application/json' } }); // Add token to requests api.interceptors.request.use((config) => { const token = localStorage.getItem('access_token'); if (token) { config.headers.Authorization = `Bearer ${token}`; } return config; }); // Login export const login = (email, password) => api.post('/auth/login', { email, password }); // Register export const register = (email, password, user_name) => api.post('/auth/register', { email, password, user_name }); // Get current user export const getCurrentUser = () => api.get('/auth/me'); // Refresh token export const refreshToken = (refresh_token) => api.post('/auth/refresh', { refresh_token }); ``` --- ## ๐Ÿงช Postman Collection You can import these endpoints into Postman: **Environment Variables:** ``` base_url: http://localhost:8080 access_token: {{access_token}} ``` **Collection Structure:** ``` GAuth-Central API โ”œโ”€โ”€ Public โ”‚ โ”œโ”€โ”€ Register โ”‚ โ”œโ”€โ”€ Login โ”‚ โ”œโ”€โ”€ Verify Email โ”‚ โ”œโ”€โ”€ Refresh Token โ”‚ โ”œโ”€โ”€ OAuth Google โ”‚ โ””โ”€โ”€ OAuth GitHub โ””โ”€โ”€ Protected (Auth Required) โ”œโ”€โ”€ Get Current User โ””โ”€โ”€ Validate Token ``` --- ## ๐Ÿ“š Additional Resources - **Swagger Documentation**: http://localhost:8080/docs/index.html - **API Version**: v1.0 - **Last Updated**: February 4, 2026 --- ## โšก Quick Start ```bash # 1. Start the server go run main.go # 2. Test with curl curl http://localhost:8080/ # 3. Register a user curl -X POST http://localhost:8080/v1/auth/register \ -H "Content-Type: application/json" \ -d '{"email":"test@test.com","password":"Test123!","user_name":"testuser"}' # 4. Login curl -X POST http://localhost:8080/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"test@test.com","password":"Test123!"}' # 5. Use the token from login response curl http://localhost:8080/v1/auth/me \ -H "Authorization: Bearer YOUR_TOKEN_HERE" ``` --- ๐Ÿ’ก **Tip**: Use the Swagger UI at http://localhost:8080/docs/index.html for interactive API testing!