Overview
The Zochil API uses token-based authentication with access tokens and device IDs. All API requests must include proper authentication headers to access protected resources.
Authentication Methods
Access Token Authentication
Most API endpoints require an access-token header:
curl -H "access-token: your_access_token_here" \
-H "device-id: your_device_id_here" \
https://api.zochil.io/user/profile
Admin Authentication
Admin endpoints also require a merchant-id header:
curl -H "access-token: admin_access_token" \
-H "device-id: admin_device_id" \
-H "merchant-id: merchant_uuid" \
https://api.zochil.io/admin/users
JWT token for user authentication. Obtained from login or registration
endpoints.
Unique identifier for the client device. Used for session management and
security.
Required for admin and order API endpoints. Identifies the merchant/shop
context.
User Authentication Flow
1. User Registration
curl -X POST "https://api.zochil.io/user/register" \
-H "Content-Type: application/json" \
-H "device-id: unique_device_id" \
-d '{
"email": "[email protected]",
"password": "secure_password",
"name": "John Doe",
"phone": "+1234567890"
}'
2. User Login
curl -X POST "https://api.zochil.io/user/login" \
-H "Content-Type: application/json" \
-H "device-id: unique_device_id" \
-d '{
"email": "[email protected]",
"password": "secure_password"
}'
3. Using the Access Token
Once you have an access token, include it in all subsequent requests:
const userProfile = await fetch("https://api.zochil.io/user/profile", {
headers: {
"access-token": access_token,
"device-id": "unique_device_id"
}
});
Admin Authentication
Admin users have additional privileges and can access merchant-specific data:
// Admin login
const adminResponse = await fetch("https://api.zochil.io/admin/login", {
method: "POST",
headers: {
"Content-Type": "application/json",
"device-id": "admin_device_id"
},
body: JSON.stringify({
email: "[email protected]",
password: "admin_password"
})
});
const { access_token, user } = await adminResponse.json();
// Access merchant data
const merchantData = await fetch("https://api.zochil.io/admin/dashboard", {
headers: {
"access-token": access_token,
"device-id": "admin_device_id",
"merchant-id": user.merchant_id
}
});
Token Storage and Management
Token Storage
- User tokens: Stored in Redis with expiration
- Admin tokens: Stored in Redis with role-based metadata
- Device tokens: Stored in the devices table for session tracking
Token Expiration
- Tokens typically expire after 24 hours
- Refresh tokens may be available for long-lived sessions
- Always handle token expiration gracefully in your application
Security Best Practices
Never expose access tokens in client-side code or URLs. Always store tokens
securely and transmit them over HTTPS.
Recommended Practices
- Secure Storage: Store tokens in secure, HTTP-only cookies or encrypted local storage
- HTTPS Only: Always use HTTPS for API requests containing tokens
- Token Rotation: Implement token refresh mechanisms for long-lived applications
- Device Management: Generate unique device IDs for each client installation
- Logout Handling: Properly invalidate tokens on logout
Example Secure Implementation
class ZochilAPIClient {
constructor() {
this.baseURL = "https://api.zochil.io";
this.accessToken = this.getSecureToken();
this.deviceId = this.getOrCreateDeviceId();
}
getSecureToken() {
// Retrieve from secure storage
return localStorage.getItem("zochil_access_token");
}
getOrCreateDeviceId() {
let deviceId = localStorage.getItem("zochil_device_id");
if (!deviceId) {
deviceId = this.generateUUID();
localStorage.setItem("zochil_device_id", deviceId);
}
return deviceId;
}
async makeRequest(endpoint, options = {}) {
const response = await fetch(`${this.baseURL}${endpoint}`, {
...options,
headers: {
"Content-Type": "application/json",
"access-token": this.accessToken,
"device-id": this.deviceId,
...options.headers
}
});
if (response.status === 401) {
// Handle token expiration
this.handleTokenExpiration();
throw new Error("Authentication required");
}
return response.json();
}
}
Error Handling
Common authentication errors and their meanings:
| Status Code | Error Code | Description |
|---|
| 401 | UNAUTHORIZED | Invalid or expired access token |
| 401 | MISSING_TOKEN | Access token not provided |
| 401 | INVALID_DEVICE | Device ID not recognized |
| 403 | INSUFFICIENT_PERMISSIONS | User lacks required permissions |
| 403 | MERCHANT_ACCESS_DENIED | Invalid merchant context |
Next Steps
