Quickstart

Prerequisites

Before starting, make sure you have:

A Firebase project with Phone Authentication enabled
The MechZie API base URL
socket_io_client and razorpay_flutter packages in your Flutter project

API Environments

Production

https://mechzie-api-production.run.app/api/v1

Local Development

http://localhost:3000/api/v1

Client SDK Dependencies

# pubspec.yaml
dependencies:
  firebase_auth: ^5.0.0
  socket_io_client: ^3.0.0
  razorpay_flutter: ^1.3.0
  flutter_secure_storage: ^9.0.0

Authenticate and Make Your First Call

Use the Firebase Auth SDK to verify the user’s phone number. This happens entirely client-side — the MechZie API is not involved yet.

await FirebaseAuth.instance.verifyPhoneNumber(
  phoneNumber: '+919876543210',
  codeSent: (verificationId, _) {
    // Store verificationId, then verify the OTP code:
    final credential = PhoneAuthProvider.credential(
      verificationId: verificationId,
      smsCode: userEnteredCode,
    );
    final result = await FirebaseAuth.instance.signInWithCredential(credential);
    final firebaseIdToken = await result.user!.getIdToken();
  },
  verificationCompleted: (_) {},
  verificationFailed: (e) => print(e),
  codeAutoRetrievalTimeout: (_) {},
);

Exchange Firebase token for MechZie JWT

Send the Firebase ID token to get your access and refresh tokens:

curl -X POST http://localhost:3000/api/v1/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "firebaseIdToken": "eyJhbGciOiJSUzI1NiIs...",
    "role": "customer"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "a1b2c3d4e5f6...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "+919876543210",
    "name": null,
    "role": "customer"
  }
}

The access token expires in 15 minutes. The refresh token is valid for 30 days. See Authentication for the full refresh flow.

Fetch your profile

Use the access token to make authenticated requests:

curl -X GET http://localhost:3000/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "phone": "+919876543210",
  "name": null,
  "email": null,
  "role": "customer",
  "avatar_url": null,
  "created_at": "2026-05-21T10:00:00.000Z",
  "updated_at": "2026-05-21T10:00:00.000Z"
}

If you get your user profile back, you’re authenticated and ready to go!

Create Your First Job

curl -X POST http://localhost:3000/api/v1/jobs \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_category_id": "uuid-of-service-category",
    "pickup_address": "MG Road, Bangalore, Karnataka",
    "pickup_lat": 12.9716,
    "pickup_lng": 77.5946,
    "description": "Flat tire, need roadside help"
  }'

To get valid service_category_id values, first call GET /api/v1/service-categories. Optionally include vehicle_id (from GET /api/v1/vehicles) and photo_urls (from File Uploads).

Next Steps

Authentication

Token refresh, logout, admin invite flow

Real-time Events

Socket.io connection, live tracking, dispatch events

Job Lifecycle

State machine, dispatch tiers, cancellation rules

Payments

Razorpay checkout, webhook, cancellation fees

Error Handling

Error codes, rate limits, pagination

API Reference

All 56 REST endpoints with interactive examples

Always use HTTPS in production. Store tokens in secure storage (e.g., flutter_secure_storage), never in SharedPreferences.

Getting Started

Guides

Development

Prerequisites

API Environments

Production

Local Development

Client SDK Dependencies

Authenticate and Make Your First Call

Create Your First Job

Next Steps

Authentication

Real-time Events

Job Lifecycle

Payments

Error Handling

API Reference

​Prerequisites

​API Environments

Production

Local Development

​Client SDK Dependencies

​Authenticate and Make Your First Call

​Create Your First Job

​Next Steps

Authentication

Real-time Events

Job Lifecycle

Payments

Error Handling

API Reference

Prerequisites

API Environments

Client SDK Dependencies

Authenticate and Make Your First Call

Create Your First Job

Next Steps