System, Auth & SaaS Management APIs

0. Developer Getting Started, Security & API Access Rules

1. How to Register & Obtain an API Key

1. Create an Account: Visit /register.php or call POST /api/v1/auth/register with your email and password.
2. Choose a Subscription Plan: Review options at /pricing.php and activate your desired tier (Starter, Growth, Scale, or Enterprise).
3. Obtain Your API Key: Log in to your Developer Dashboard to copy your production key (sk_live_...).
4. Configure Anti-Theft Domain Whitelist: In your dashboard, specify your client domains (e.g. app.mywebsite.com, localhost, *.client.in). Requests originating from unlisted domains will be blocked immediately with HTTP 403.

2. Authentication & Request Headers

Every API request must supply valid authentication credentials using either of the following standard headers:

X-API-Key: sk_live_your_api_key_here

or

Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json

3. Tier-Based API Access Hierarchy

4. HTTP Status Codes & Structured Error Responses

• 200 OK: Calculation executed successfully with verified astronomical accuracy.
• 401 Unauthorized: Missing or invalid API key.

  {
    "status": "error",
    "code": 401,
    "message": "Missing API Key. Pass your key via X-API-Key or Authorization: Bearer header."
  }

• 403 Forbidden (Tier Restricted): Attempting to call an endpoint above your active plan tier.

  {
    "status": "error",
    "code": 403,
    "error": "Tier Restricted: Endpoint '/api/v1/kp' requires Growth Plan (Level 2) or higher.",
    "current_tier": "starter",
    "required_tier": "growth",
    "upgrade_url": "/pricing.php"
  }

• 403 Forbidden (Domain Unauthorized): Attempting to call the API from an unauthorized website origin.

  {
    "status": "error",
    "code": 403,
    "message": "Domain Unauthorized: Origin 'https://unauthorized-domain.com' is not in the allowed domains list for this API Key."
  }

• 429 Too Many Requests: Monthly request quota reached or per-second rate limit exceeded.

  {
    "status": "error",
    "code": 429,
    "message": "Monthly Quota Exceeded: Your plan limit of 1,000 requests has been reached. Please upgrade at /pricing.php."
  }

1. Developer Authentication & Registration

1. Name

Developer Authentication & Registration

2. Purpose

Provides account creation (/auth/register) and JWT token authentication (/auth/login) for developers creating accounts on the RBOS.in SaaS platform.

3. Endpoint

POST /api/v1/auth/register & POST /api/v1/auth/login

4. Auth

Type: None (Public Auth Endpoint)

5. Request Headers

6. Request Payload

{
  "email": "developer@example.com",
  "password": "SecurePassword123!"
}

7. Request Params Table

8. Request Example

{
  "email": "developer@example.com",
  "password": "SecurePassword123!"
}

9. Success Response

Status: 200 OK (or 201 Created)

{
  "status": "success",
  "message": "Authentication successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "email": "developer@example.com",
      "plan": "free"
    }
  }
}

10. Response Fields Table

11. Status Codes Table

12. Error Examples

{
  "status": "error",
  "message": "Invalid email or password."
}

13. Frontend Usage Notes

• Store token in HTTPOnly Cookie or Secure Storage for Dashboard session authorization.

14. Validation Rules

• Password min 8 chars.

15. Business Rules

• Registration automatically provisions a Free Tier subscription and an initial X-API-Key.

16. Security Notes

• Passwords hashed using password_hash() with PASSWORD_BCRYPT.

17. Performance Notes

• Fast (< 50ms).

18. Related APIs

• GET /api/v1/dashboard/me

19. Example Frontend Flow

1. Developer submits login form.
2. App posts to /api/v1/auth/login.
3. App redirects to /dashboard/me.

20. Complete Example

Request:

POST /api/v1/auth/login HTTP/1.1
Host: api.rbos.in
Content-Type: application/json

{
  "email": "developer@example.com",
  "password": "SecurePassword123!"
}

Response:

{
  "status": "success",
  "data": { "token": "jwt_token_here", "user": { "id": 1, "email": "developer@example.com" } }
}

Explanation: Authenticates developer and returns JWT token.

2. API Health Check

1. Name

API Health Check

2. Purpose

Used by load balancers, uptime monitors, and frontend status bars to verify API engine operational status.

3. Endpoint

GET /api/v1/health

4. Auth

Type: None

5. Request Headers

6. Request Payload

None (GET Request)

7. Request Params Table

None

8. Request Example

GET /api/v1/health

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "RBOS Engine API is running"
}

10. Response Fields Table

11. Status Codes Table

12. Error Examples

500 Internal Server Error if database or Swiss Ephemeris binaries fail initialization.

13. Frontend Usage Notes

• Poll every 60s for status badges in the developer portal footer.

14. Validation Rules

None.

15. Business Rules

• Lightweight zero-DB ping response.

16. Security Notes

• Public health endpoint.

17. Performance Notes

• Instant (< 5ms).

18. Related APIs

• GET /api/v1/dashboard/usage

19. Example Frontend Flow

1. Developer portal loads.
2. Portal sends GET /api/v1/health.
3. Green indicator rendered.

20. Complete Example

Request:

GET /api/v1/health HTTP/1.1
Host: api.rbos.in

Response:

{
  "status": "success",
  "message": "RBOS Engine API is running"
}

Explanation: Confirms engine availability.