Skip to main content

​
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

1

Sign in with Firebase Phone OTP

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: (_) {},
);
2

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.
3

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.