CODITECT Cloud Backend - API Quick Reference

Base URL

Development: http://localhost:8000
Production:  https://api.coditect.az1.ai

Authentication Endpoints

1. Signup (Create User + Organization)

POST /api/v1/auth/signup
Content-Type: application/json

{
  "email": "john@example.com",
  "username": "johndoe",
  "password": "SecureP@ss123",
  "full_name": "John Doe",
  "organization_name": "Acme Corporation",
  "organization_slug": "acme-corp"
}

Response (201 Created):

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john@example.com",
    "username": "johndoe",
    "role": "OWNER",
    "organization_id": "223e4567-e89b-12d3-a456-426614174000"
  },
  "organization": {
    "id": "223e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "plan": "FREE"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

2. Login

POST /api/v1/auth/login
Content-Type: application/json

# Option 1: Login with email
{
  "email": "john@example.com",
  "password": "SecureP@ss123"
}

# Option 2: Login with username
{
  "username": "johndoe",
  "password": "SecureP@ss123"
}

Response (200 OK):

{
  "user": { ... },
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600
}

3. Get Current User

GET /api/v1/auth/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response (200 OK):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john@example.com",
  "username": "johndoe",
  "full_name": "John Doe",
  "role": "OWNER",
  "organization_id": "223e4567-e89b-12d3-a456-426614174000",
  "license_status": "ACTIVE",
  "is_active": true,
  "email_verified": false
}

4. Refresh Access Token

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600
}

Health & Info Endpoints

Health Check

GET /health

Response (200 OK):

{
  "status": "healthy",
  "service": "CODITECT Cloud Backend",
  "version": "1.0.0",
  "environment": "development"
}

API Root

GET /

Response (200 OK):

{
  "service": "CODITECT Cloud Backend",
  "version": "1.0.0",
  "docs": "/docs",
  "health": "/health"
}

Error Responses

All errors follow RFC 7807 Problem Details format:

400 Bad Request

{
  "type": "https://api.coditect.az1.ai/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request body or parameters",
  "instance": "/api/v1/auth/signup"
}

401 Unauthorized

{
  "type": "https://api.coditect.az1.ai/errors/unauthorized",
  "title": "Authentication Failed",
  "status": 401,
  "detail": "Invalid email or password",
  "instance": "/api/v1/auth/login"
}

409 Conflict

{
  "type": "https://api.coditect.az1.ai/errors/conflict",
  "title": "Resource Conflict",
  "status": 409,
  "detail": "Email address john@example.com is already registered",
  "instance": "/api/v1/auth/signup"
}

422 Validation Error

{
  "type": "https://api.coditect.az1.ai/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request validation failed",
  "instance": "/api/v1/auth/signup",
  "errors": [
    {
      "field": "password",
      "message": "Password must contain at least one uppercase letter"
    }
  ]
}

cURL Examples

Complete Signup Flow

# 1. Signup
curl -X POST http://localhost:8000/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "username": "testuser",
    "password": "SecureP@ss123",
    "full_name": "Test User",
    "organization_name": "Test Org",
    "organization_slug": "test-org"
  }' | jq .

# 2. Extract access token
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": "SecureP@ss123"}' \
  | jq -r .access_token)

# 3. Get current user
curl http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN" | jq .

Password Requirements

• Minimum 8 characters
• At least one uppercase letter (A-Z)
• At least one lowercase letter (a-z)
• At least one digit (0-9)
• At least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?)

Valid Examples:

• SecureP@ss123
• MyP@ssw0rd!
• C0ditect#2025

Invalid Examples:

• password (no uppercase, no number, no special)
• PASSWORD123 (no lowercase, no special)
• Pass123 (no special character)

Token Lifetimes

Token Type	Lifetime	Purpose
Access Token	1 hour	API authentication
Refresh Token	7 days	Get new access tokens

Token Refresh Strategy:

1. Use access token for all API requests
2. When access token expires (401 error), use refresh token to get new access token
3. When refresh token expires, user must login again

User Roles

Role	Permissions
OWNER	Full control of organization
ADMIN	Manage users and projects
MEMBER	Create and manage own projects
GUEST	Read-only access

Organization Plans

Plan	Max Users	Max Projects	Features
FREE	5	10	Basic features
PRO	50	Unlimited	Advanced features
ENTERPRISE	Unlimited	Unlimited	All features

Interactive API Documentation

When running in debug mode (DEBUG=true):

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Both provide:

• Complete API documentation
• Interactive testing
• Schema definitions
• Example requests/responses

Postman Collection

Import this URL into Postman:

http://localhost:8000/openapi.json

Or use the OpenAPI specification:

/path/to/coditect-cloud-backend/openapi.yaml

Common Issues

"Missing authentication token"

• Add Authorization: Bearer <token> header to request
• Check token hasn't expired (1 hour for access tokens)

"Could not validate credentials"

• Token may be expired - use refresh token to get new access token
• Token may be invalid - login again to get new tokens

"Email address already registered"

• Email is unique across all organizations
• Use a different email or login with existing account

"Organization slug already taken"

• Organization slugs must be unique
• Choose a different slug

---

Last Updated: November 17, 2025 API Version: 1.0.0 For detailed documentation: See readme-backend.md