beyhan/AuthCentral
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Beyhan Oğur
2026-04-26 21:37:58 +03:00
commit 8b1fbdee99
104 changed files with 23398 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

590
API_ENDPOINTS.md Normal file
View File

@@ -0,0 +1,590 @@
# 🌐 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!