beyhan/AuthCentral
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8b1fbdee991a569250f111a4b5bbea6e6953bbea
AuthCentral/API_ENDPOINTS.md
Beyhan Oğur 8b1fbdee99 first commit
2026-04-26 21:37:58 +03:00

10 KiB
Raw Blame History

🌐 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:

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "user_name": "username"
}

Response (201):

{
  "message": "User created successfully. Please verify your email.",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_name": "username"
  }
}

cURL Example:

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:

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Response (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_name": "username"
  }
}

cURL Example:

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):

{
  "message": "Email verified successfully"
}

cURL Example:

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):

{
  "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:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

cURL Example:

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):

{
  "id": "uuid",
  "email": "user@example.com",
  "user_name": "username",
  "email_verified": true,
  "created_at": "2026-02-04T00:00:00Z"
}

cURL Example:

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):

{
  "message": "Token is valid",
  "user_id": "uuid",
  "email": "user@example.com"
}

cURL Example:

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

{
  "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

{
  "message": "Operation successful",
  "data": { ... }
}

Error Response

{
  "error": "Invalid credentials"
}

Validation Error

{
  "error": "Validation failed: email is required"
}

🔗 Frontend Integration

JavaScript/TypeScript Example

// 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

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

⚡ Quick Start

# 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!

Reference in New Issue View Git Blame Copy Permalink