# Quick Start Guide - Tenant Provisioning API

## 🚀 5-Minute Setup

### Prerequisites
- Docker containers running (`docker ps` shows `taskco-nginx`, `taskco-app`)
- Postman installed

---

## Method 1: Using Postman (Recommended)

### Step 1: Import Collection

1. Open Postman
2. Click **Import** → **File**
3. Select: `/home/shakib/Dev/projects/saas-docker/postman/tenant-provisioning-api-v2.json`

### Step 2: Set Base URL

1. Click on collection "Tenant Provisioning API v2"
2. Go to **Variables** tab
3. Set `baseUrl` to: `http://localhost:81`
4. Click **Save**

### Step 3: Test the API

**3a. Generate Token**
- Expand **"1. Authentication"**
- Run: **"Generate Token (Provision Scope)"**
- ✅ Token will be auto-saved

**3b. Provision Tenant**
- Expand **"2. Tenant Provisioning"**
- Run: **"Provision Tenant (Full Data)"**
- ✅ You'll get a `job_id` in response

**3c. Check Status (Optional)**
- First generate status token: Run **"Generate Token (Status Scope)"**
- Then run: **"Check Provisioning Status"**
- See if tenant provisioning completed

---

## Method 2: Using curl

### Step 1: Generate Token

```bash
cd /home/shakib/Dev/projects/saas-docker

# Generate token
TOKEN=$(php generate-token.php tenant:provision)
echo "Token: $TOKEN"
```

### Step 2: Provision Tenant

```bash
curl -X POST http://localhost:81/api/internal/tenants/provision \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "tenant_uid": "tnt-demo-001",
    "encrypted_credentials": "eyJkYl9ob3N0IjoibG9jYWxob3N0IiwiZGJfcG9ydCI6MzMwNiwiZGJfdXNlciI6InRlbmFudF91c2VyIiwiZGJfcGFzcyI6InNlY3VyZV9wYXNzd29yZCJ9",
    "tenant_data": {
      "company_name": "Demo Company",
      "slug": "demo-company",
      "email": "admin@demo.com",
      "admin_password": "SecureP@ss123!",
      "admin_name": "Demo Admin"
    }
  }' | python3 -m json.tool
```

**Expected Response:**
```json
{
    "status": "SUCCESS",
    "message": "Tenant database provisioning initiated",
    "data": {
        "job_id": "job_01KDVZCYZJMWZY2F0CKC5DD7PS",
        "tenant_uid": "tnt-demo-001",
        "status": "processing"
    }
}
```

---

## Common Issues

### ❌ Error: "Connection refused" on port 81

**Fix:**
```bash
# Check if nginx is exposing port 81
docker ps --filter "name=taskco-nginx" --format "{{.Ports}}"

# Should show: 0.0.0.0:81->80/tcp

# If not, restart nginx:
docker compose down nginx && docker compose up -d nginx
```

---

### ❌ Error: "Token verification failed"

**Fix:**
```bash
# Regenerate matching keys
docker exec taskco-app openssl genrsa -out /var/www/html/storage/keys/saas_admin_jwt_private.pem 2048
docker exec taskco-app openssl rsa -in /var/www/html/storage/keys/saas_admin_jwt_private.pem -pubout -out /var/www/html/storage/keys/saas_admin_jwt_public.pem

# Clear config cache
docker exec taskco-app php artisan config:clear

# Generate new token
TOKEN=$(php generate-token.php tenant:provision)
```

---

### ❌ Error: "Validation failed"

Common validation issues:

| Error | Fix |
|-------|-----|
| `tenant_uid` uppercase | Use lowercase only: `tnt-demo-001` |
| `slug` has underscore | Use hyphens: `demo-company` not `demo_company` |
| `admin_password` too short | Min 8 characters |
| `encrypted_credentials` too short | Min 100 characters (base64) |

---

## Next Steps

📖 **Full Documentation:** `/home/shakib/Dev/projects/saas-docker/API-DOCUMENTATION.md`

📬 **Postman Collection:** `/home/shakib/Dev/projects/saas-docker/postman/tenant-provisioning-api-v2.json`

🔧 **Test Script:** `/home/shakib/Dev/projects/saas-docker/generate-token.php`

---

## API Endpoints Summary

| Endpoint | Method | Scope | Port |
|----------|--------|-------|------|
| `/api/internal/tenants/provision` | POST | `tenant:provision` | 81 |
| `/api/internal/tenants/provision/status/{id}` | GET | `tenant:status` | 81 |

**Base URL:** `http://localhost:81`

---

## Testing Checklist

- [ ] Port 81 accessible: `curl http://localhost:81/health`
- [ ] Token generation works: `php generate-token.php tenant:provision`
- [ ] Postman collection imported
- [ ] First API call successful (202 Accepted response)
- [ ] Job ID received in response

✅ **You're ready to integrate the API!**