Getting Started

Welcome to the ZoneVast developer documentation. This guide walks you through everything you need to start integrating with our backend services.

Architecture Overview

ZoneVast uses a microservices architecture. Each service handles a specific domain:

Service	Purpose
zv-auth-service	Authentication & JWT tokens
zv-flex-auth-service	Phone-based auth (OTP)
zv-project-service	Project management & file attachments

Prerequisites

• An HTTP client (curl, Postman, or axios/fetch)
• A project with a valid X-Project-ID — create one via the Project Service (see below)
• Auth credentials (phone + password, or phone + OTP)

Create a Project

All API requests require a X-Project-ID header. To create a project and get your ID:

curl -X POST https://test.zonevast.com/api/v1/project/project/projects/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Project",
    "username": "my-project",
    "template": "default"
  }'

Response will include the project id — use this value as your X-Project-ID in all subsequent requests.

Testing: For quick testing, use X-Project-ID: <project-id> which is the default test project.

Environment URLs

Environment	Base URL
Test (dev)	https://test.zonevast.com
Production	https://api.zonevast.com
Local	http://localhost:{service-port}

Each service has its own path prefix:

https://test.zonevast.com/api/v1/auth/auth/     # Auth service
https://test.zonevast.com/auth/api/v2/auth/      # Flex Auth service
https://test.zonevast.com/api/v1/project/project/ # Project service

Required Headers

Every authenticated request must include:

const headers = {
  'Authorization': `Bearer ${accessToken}`,
  'X-Project-ID': '<project-id>',
  'Content-Type': 'application/json',
};

Important: X-Project-ID is required for all services. Users and data are isolated per project.

Your First API Call

Step 1: Login

Using password auth (zv-auth-service):

curl -X POST https://test.zonevast.com/api/v1/auth/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

Using phone OTP (zv-flex-auth-service):

# Send OTP
curl -X POST https://test.zonevast.com/auth/api/v2/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "+9647500000001", "projectId": <project-id>}'

# Login with OTP
curl -X POST https://test.zonevast.com/auth/api/v2/auth/login-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "+9647500000001", "otp": "123456", "projectId": <project-id>}'

Step 2: Use the Token

curl https://test.zonevast.com/api/v1/auth/auth/user/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Project-ID: <project-id>"

Step 3: Refresh When Expired

curl -X POST https://test.zonevast.com/api/v1/auth/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'

Test Credentials

Phone	OTP	Notes
+9647500000001	123456	Seed test user
+9647500000002	123456	Seed test user

Common Patterns

TypeScript API Client

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://test.zonevast.com',
  headers: {
    'X-Project-ID': '<project-id>',
    'Content-Type': 'application/json',
  },
});

// Add auth token interceptor
api.interceptors.request.use((config) => {
  const token = getAccessToken(); // your token storage
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Auto-refresh on 401
api.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401) {
      const newToken = await refreshToken();
      error.config.headers.Authorization = `Bearer ${newToken}`;
      return api.request(error.config);
    }
    return Promise.reject(error);
  }
);

Next Steps

• API Response Format — How responses are structured
• Headers & Authentication Reference - Deep dive into auth flows
• Flex Auth Service - Phone + OTP authentication
• Auth Service - Email + password authentication
• Project Service - File uploads and project management
• Error Responses - Error format across services
• Pagination - How list pagination works