# Provisioning API Server\n\nA comprehensive REST API server for remote provisioning operations, enabling thin clients and CI/CD pipeline integration.\n\n> **Source**: `provisioning/platform/provisioning-server/`\n\n## Features\n\n- **Comprehensive REST API**: Complete provisioning operations via HTTP\n- **JWT Authentication**: Secure token-based authentication\n- **RBAC System**: Role-based access control (Admin, Operator, Developer, Viewer)\n- **Async Operations**: Long-running tasks with status tracking\n- **Nushell Integration**: Direct execution of provisioning CLI commands\n- **Audit Logging**: Complete operation tracking for compliance\n- **Metrics**: Prometheus-compatible metrics endpoint\n- **CORS Support**: Configurable cross-origin resource sharing\n- **Health Checks**: Built-in health and readiness endpoints\n\n## Architecture\n\n```\n┌─────────────────┐\n│  REST Client    │\n│  (curl, CI/CD)  │\n└────────┬────────┘\n         │ HTTPS/JWT\n         ▼\n┌─────────────────┐\n│  API Gateway    │\n│  - Routes       │\n│  - Auth         │\n│  - RBAC         │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│ Async Task Mgr  │\n│ - Queue         │\n│  - Status       │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│ Nushell Exec    │\n│ - CLI wrapper   │\n│ - Timeout       │\n└─────────────────┘\n```\n\n## Installation\n\n```\ncd provisioning/platform/provisioning-server\ncargo build --release\n```\n\n## Configuration\n\nCreate `config.toml`:\n\n```\n[server]\nhost = "0.0.0.0"\nport = 8083\ncors_enabled = true\n\n[auth]\njwt_secret = "your-secret-key-here"\ntoken_expiry_hours = 24\nrefresh_token_expiry_hours = 168\n\n[provisioning]\ncli_path = "/usr/local/bin/provisioning"\ntimeout_seconds = 300\nmax_concurrent_operations = 10\n\n[logging]\nlevel = "info"\njson_format = false\n```\n\n## Usage\n\n### Starting the Server\n\n```\n# Using config file\nprovisioning-server --config config.toml\n\n# Custom settings\nprovisioning-server \\n  --host 0.0.0.0 \\n  --port 8083 \\n  --jwt-secret "my-secret" \\n  --cli-path "/usr/local/bin/provisioning" \\n  --log-level debug\n```\n\n### Authentication\n\n#### Login\n\n```\ncurl -X POST http://localhost:8083/v1/auth/login \\n  -H "Content-Type: application/json" \\n  -d '{\n    "username": "admin",\n    "password": "admin123"\n  }'\n```\n\nResponse:\n\n```\n{\n  "token": "eyJhbGc...",\n  "refresh_token": "eyJhbGc...",\n  "expires_in": 86400\n}\n```\n\n#### Using Token\n\n```\nexport TOKEN="eyJhbGc..."\n\ncurl -X GET http://localhost:8083/v1/servers \\n  -H "Authorization: Bearer $TOKEN"\n```\n\n## API Endpoints\n\n### Authentication\n\n- `POST /v1/auth/login` - User login\n- `POST /v1/auth/refresh` - Refresh access token\n\n### Servers\n\n- `GET /v1/servers` - List all servers\n- `POST /v1/servers/create` - Create new server\n- `DELETE /v1/servers/{id}` - Delete server\n- `GET /v1/servers/{id}/status` - Get server status\n\n### Taskservs\n\n- `GET /v1/taskservs` - List all taskservs\n- `POST /v1/taskservs/create` - Create taskserv\n- `DELETE /v1/taskservs/{id}` - Delete taskserv\n- `GET /v1/taskservs/{id}/status` - Get taskserv status\n\n### Workflows\n\n- `POST /v1/workflows/submit` - Submit workflow\n- `GET /v1/workflows/{id}` - Get workflow details\n- `GET /v1/workflows/{id}/status` - Get workflow status\n- `POST /v1/workflows/{id}/cancel` - Cancel workflow\n\n### Operations\n\n- `GET /v1/operations` - List all operations\n- `GET /v1/operations/{id}` - Get operation status\n- `POST /v1/operations/{id}/cancel` - Cancel operation\n\n### System\n\n- `GET /health` - Health check (no auth required)\n- `GET /v1/version` - Version information\n- `GET /v1/metrics` - Prometheus metrics\n\n## RBAC Roles\n\n### Admin Role\n\nFull system access including all operations, workspace management, and system administration.\n\n### Operator Role\n\nInfrastructure operations including create/delete servers, taskservs, clusters, and workflow management.\n\n### Developer Role\n\nRead access plus SSH to servers, view workflows and operations.\n\n### Viewer Role\n\nRead-only access to all resources and status information.\n\n## Security Best Practices\n\n1. **Change Default Credentials**: Update all default usernames/passwords\n2. **Use Strong JWT Secret**: Generate secure random string (32+ characters)\n3. **Enable TLS**: Use HTTPS in production\n4. **Restrict CORS**: Configure specific allowed origins\n5. **Enable mTLS**: For client certificate authentication\n6. **Regular Token Rotation**: Implement token refresh strategy\n7. **Audit Logging**: Enable audit logs for compliance\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```\n- name: Deploy Infrastructure\n  run: |\n    TOKEN=$(curl -X POST https://api.example.com/v1/auth/login \\n      -H "Content-Type: application/json" \\n      -d '{"username":"${{ secrets.API_USER }}","password":"${{ secrets.API_PASS }}"}' \\n      | jq -r '.token')\n    \n    curl -X POST https://api.example.com/v1/servers/create \\n      -H "Authorization: Bearer $TOKEN" \\n      -H "Content-Type: application/json" \\n      -d '{"workspace": "production", "provider": "upcloud", "plan": "2xCPU-4 GB"}'\n```\n\n## Related Documentation\n\n- **API Reference**: [REST API Documentation](../api/rest-api.md)\n- **Architecture**: [API Gateway Integration](../architecture/integration-patterns.md)
