API Documentation

TikShip provides a comprehensive RESTful API for all platform features.

Interactive API Documentation

For interactive API documentation with live testing:

Visit locally: http://localhost:3000/api-docs

Authentication

User Authentication

User endpoints use NextAuth session-based authentication:

const response = await fetch('/api/user/profile', {
  credentials: 'include',
})

Admin Authentication

Admin endpoints use cookie-based JWT authentication. First call the login endpoint — it sets an admin-token httpOnly cookie automatically:

// Step 1: Login (sets admin-token cookie)
const loginRes = await fetch('/api/admin/auth/login', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'admin', password: 'password' }),
})

// Step 2: Subsequent requests include the cookie automatically
const response = await fetch('/api/admin/users', {
  credentials: 'include',
})

The server reads the admin-token cookie and resolves the admin user ID via requireAdminAuth(). No manual Authorization header is needed.

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• POST /api/admin/auth/login - Admin login

Users

• GET /api/user/profile - Get current user profile
• PATCH /api/user/profile - Update user profile
• POST /api/user/change-password - Change password

Admin - Users

• GET /api/admin/users - List all users
• GET /api/admin/users/:id - Get user details
• PATCH /api/admin/users/:id - Update user
• DELETE /api/admin/users/:id - Delete user

Posts

• GET /api/posts - List published posts
• GET /api/posts/:slug - Get post by slug
• POST /api/admin/posts - Create post (admin)
• PATCH /api/admin/posts/:id - Update post (admin)

Products

• GET /api/products - List active products
• GET /api/products/:id - Get product details
• POST /api/admin/products - Create product (admin)

Orders

• GET /api/user/orders - Get user's orders
• GET /api/admin/orders - List all orders (admin)

Payments

• POST /api/payments/stripe/checkout - Create Stripe checkout
• POST /api/payments/paypal/create-order - Create PayPal order
• POST /api/webhooks/stripe - Stripe webhook handler
• POST /api/webhooks/paypal - PayPal webhook handler

Response Format

Success Response

{
  "success": true,
  "data": {},
  "message": "Operation successful"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "message": "User-friendly error message"
}

Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error

Next Steps

• View locally Interactive API Docs
• Explore Components