Migrate from v1 to v4

The purpose of this document is to provide developers with clear guidance on how to migrate existing integrations from Azuga API v1 to API v4, our latest and most optimised API release. API v4 introduces OPEN API specifications, modern authentication methods, improved performance, standardised data models, and structured error handling to ensure a more reliable integration experience. It explains the major changes, improvements, and requirements introduced in API v4 to ensure a smooth and successful transition.

New Features in API v4

• OPEN API Specification 
• Adhere to REST API Standards 
• OAuth 2.0 based authentication (replaces API Key) 
• Unified endpoint structure (/vehicles, /trips, /alerts, etc.) 
• Standardized and consistent response formats (consistent id, status, timestamp fields) 
• Improved error messages and standard HTTP status codes 
• Webhooks for real-time updates  and data flow

Breaking Changes Summary 

Migration Steps 

Step 1: Update Authentication 

1. Old (v1): Authentication used legacy username/password or API key in the query/header. 
2. New (v4): Authentication is OAuth 2.0–based. You must: 
   1. Base URL only for authentication: https://fleet-rest.azuga/api/v4/login 
   2. Obtain a valid access_token using the new authentication endpoint. Refer V4 authentication  API
   3. Use client credentials (client_id,  client_secret) or refresh tokens as specified.
      To obtain your clientId and clientSecret  - email “[email protected] or reach out to Azuga Support” 
   4. Store and refresh tokens securely — tokens expire periodically i.e 180 days. 

Action Items: 

• Remove any static or hardcoded API keys. 
• Implement token generation and refresh logic. 

Step 2: Pass Access Token as Bearer Token in Header 

1. Replace legacy headers like X-API-Key or Authorization: Basic .  with: Authorization: Bearer <access_token>in each endpoint
2. Ensure the token is added dynamically at runtime. 
3. Validate the token expiry and handle auto-renewal using the refresh token endpoint. 

Step 3: Update the Base URL 

1. Old (v1): https://api.azuga.com/azuga-ws/v1/... 
2. New (v4): https://sls.azuga.com/api/v4/... (excluding authorization) 
3. Confirm the new environment base URLs for: 
   1. Production  : https://sls.azuga.com
   2. Dev (Azuga internal)  : https://dev.azuga.com
4. Ensure that  all service references, configs, and proxy routes are updated accordingly. 

Step 4: Update Endpoint Details 

1. Endpoints have changed — names, paths, or resource groupings differ. 

• Example: 

GET /v1/vehicles → GET /v4/fleet/vehicles 
POST /v1/trips → POST /v4/telematics/trips 

2. Compare the full endpoint list from v1 and v4 documentation

2. Validate any pagination or filtering parameters that have changed. 
3. Update request method (GET, POST, PUT, DELETE) if specified differently. 

Step 5: Check the Request Methods and Fields

1. Refer to the v4 Request Methods
2. Review new mandatory fields in v4. Some previously optional fields may now be required. 
3. Field name and type changes: 
   1. eg: id to vehicleId
   2. Standardised units and metrics across all module endpoints. Refer Units and Metrics section
4. Remove deprecated parameters from requests if any
5. Ensure data formats align with v4 schema (e.g., date/time, enum values, nested objects etc ). 

Step 6: Update the Response Parameters 

1. V4 introduces structured and standardised JSON responses.  Refer Response Codes Section for implementation
2. Changes include: 
   1. Unified response envelope (data, meta, errors) 
   2. Updated field names and formats 
   3. New nested objects (for related entities) 
3. Example Response : 

v4 sample response 

{
  "generatedAt": 1681072293000,
  "message": "Vehicle Created Successfully.",
  "data": {
    "count": 10,
    "vehicles": [
    "vehicleId",":", "550f8400-e679b-41d4-a716-44665546000",
    "vehicleName",":", "Fleet Van 42",
    "customerId",": 12345",
    "vehicleTypeId",": 1",
    "vehicleType",":", "Car",
    "vehicleOwnership",":", "Company",
    "createdBy",":", "550e8400-e29b-41d4-a716-446655440005",
    "updatedBy",":", "550e8400-e29b-41d4-a716-446655440006"
]
  }
}

v1 Response: { "vehicleName": "Truck 1", "vehicleId": 123 }  

4. Update downstream systems, data mappings, and models to align with new fields. 

Step 7: Handle the Response Statuses 

1. v4 uses clearer and more consistent HTTP status codes: 

• 200 OK – Success 
• 201 Created – Resource created 

2. Update any existing logic that depends on custom response codes or messages
3. Review success/failure handling logic and logging mechanisms

200 ok - Success
{
  "generatedAt": 1681072293000,
  "errorMessage": "INTERNAL-SERVER-ERROR",
  "description": "Service is currently unavailable. Please try again later."
}

Status Code 201 - on successful object creation
{
  "generatedAt": 1681072293000,
  "message": "Vehicle Created Successfully.",
    "data": { # all the deatils of the object created}
}

Step 8: Handle the Error Codes 

1. Implement the new standardised HTTP Error Codes

• v1: Used custom numeric or string codes (e.g., "code": "E100") 
• v4: Follows standard HTTP response codes with details under errors 

Example v4 error: 

{
  "generatedAt": 1681072293000,
  "errorMessage": "INVALID-REQUEST",
  "description": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "errorDetails": [
    {
      "field": "userName",
      "description": "Required input parameter is missing or invalid. should be a string with minimum 6-chars and maximum 52-chars.",
      "code": "AZGUM-002"
    },
    {
      "field": "userName",
      "description": "Required input parameter is invalid or already exists in the system. Please provide a different value.",
      "code": "AZGUM-002"
    },
    {
      "field": "emailId",
      "description": "Required input parameter is missing or invalid. should be a string in a valid email format.",
      "code": "AZGUM-008"
    }]}  

3. Implement proper error handling logic: 

Unauthorised (401) 

{
  "generatedAt": 1708676216236,
  "errorMessage": "UNAUTHORIZED",
  "description": "User is not Authorized. Ensure that the authorization header in your request is included and valid."
}

Forbidden(403)

{
  "generatedAt": 1708676216236,
  "errorMessage": "FORBIDDEN",
  "description": "The resource requested is forbidden for your API Key"
}

Resource not found (404)

{
  "generatedAt": 1708676216236,
  "errorMessage": "METHOD-NOT-ALLOWED (or) NOT-FOUND",
  "description": "The API endpoint is invalid, or a path parameter is missing or invalid"
}

Validation error (422) 

{
  "generatedAt": 1708676216236,
  "errorMessage": "UNAUTHORIZED",
  "description": "User is not Authorized. Ensure that the authorization header in your request is included and valid."
}

Rate limit (429) 

{
  "generatedAt": 1708676216236,
  "errorMessage": "RATE-LIMIT-REACHED",
  "description": "Too many requests. You have exceeded the rate limit. Please wait for 60 seconds before retrying."
}

Internal server error (500) 

{
  "generatedAt": 1681072293000,
  "errorMessage": "INTERNAL-SERVER-ERROR",
  "description": "Service is currently unavailable. Please try again later."
}

Service Unavailable(503)

{
  "generatedAt": 1681072293000,
  "errorMessage": "SERVICE-UNAVAILABLE",
  "description": "We are temporarily ofline for maintenance. Please try again later"
}

Server Timeout (504)

{
  "generatedAt": 1681072293000,
  "errorMessage": "GATEWAY-TIMEOUT",
  "description": "The upstream service did not respond within the expected time.Please try again shortly."
}

Step 9: Validation & Testing 

1. Perform regression testing on all API-dependent modules. 
2. Validate: 

• Authentication flow 
• Endpoint reachability 
• Field mappings and payload correctness 
• Response handling 

2. Conduct performance tests to ensure response times and payload sizes remain within acceptable limits. 

Step 10: Documentation and Version Control 

1. Document all endpoint changes, field mappings, and updated workflows. 
2. Update internal API documentation, SDKs, and Postman collections. 
3. Version controls the migration of scripts/configs for traceability. 

Recommended Migration Strategy 

1. Run both APIs in parallel during testing. 
2. Start with module level end points (eg: get vehicles, create vehicles, delete vehicles etc). 
3. Use feature flags or config toggles to switch between /v4 easily. 
4. Monitor logs for 404s or 401s — common migration issues. 
5. Coordinate with your Azuga customer success manager for phased rollout. 

Validation Checklist 

1. OAuth authentication implemented 
2. Base URL updated 
3. All endpoint URLs updated 
4. Response fields renamed  and implemented the new structure
5. New Pagination logic implemented
6. Error handling is more structured 
7. Testing complete 
8. v1 endpoints deprecated in code 

Developer Resources 

1. v4 API Reference 
2. OAuth Setup Guide 
3. v1 → v4 Postman Collection 
4. Contact Developer Support 

FAQs 

1. Has the base Url changed for v4?  Ans: yes, and the link  Base Url.
2. What are the tps limits for every v4 API? 
   Ans: API v4 supports: • Per-endpoint limits • Per-module limits • Global limits Maximum Supported: 200 TPS.
3. Has the authentication method changed?
   Ans: Yes, the authentication method changed.
   v1 used API keys or username/password.
   v4 uses OAuth 2.0 and requires obtaining an access_token using client_id and client_secret.
4. Will my existing API keys work with v4?
   Ans: No, API keys are no longer supported. You must use OAuth 2.0 tokens.

📘

We welcome your feedback to help us improve this document and the API migration experience. Submit feedback via the Feedback Form