> ## Documentation Index
> Fetch the complete documentation index at: https://docs-kfhye.zochil.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Learn how to authenticate with the Zochil API using access tokens and device IDs
## 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:
```bash theme={null}
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:
```bash theme={null}
curl -H "access-token: admin_access_token" \
-H "device-id: admin_device_id" \
-H "merchant-id: merchant_uuid" \
https://api.zochil.io/admin/users
```
## Required Headers
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
```bash cURL theme={null}
curl -X POST "https://api.zochil.io/user/register" \
-H "Content-Type: application/json" \
-H "device-id: unique_device_id" \
-d '{
"email": "user@example.com",
"password": "secure_password",
"name": "John Doe",
"phone": "+1234567890"
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.zochil.io/user/register", {
method: "POST",
headers: {
"Content-Type": "application/json",
"device-id": "unique_device_id"
},
body: JSON.stringify({
email: "user@example.com",
password: "secure_password",
name: "John Doe",
phone: "+1234567890"
})
});
const data = await response.json();
const accessToken = data.data.access_token;
```
### 2. User Login
```bash cURL theme={null}
curl -X POST "https://api.zochil.io/user/login" \
-H "Content-Type: application/json" \
-H "device-id: unique_device_id" \
-d '{
"email": "user@example.com",
"password": "secure_password"
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.zochil.io/user/login", {
method: "POST",
headers: {
"Content-Type": "application/json",
"device-id": "unique_device_id"
},
body: JSON.stringify({
email: "user@example.com",
password: "secure_password"
})
});
const { access_token } = await response.json();
```
### 3. Using the Access Token
Once you have an access token, include it in all subsequent requests:
```javascript theme={null}
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:
```javascript theme={null}
// 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: "admin@merchant.com",
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
1. **Secure Storage**: Store tokens in secure, HTTP-only cookies or encrypted local storage
2. **HTTPS Only**: Always use HTTPS for API requests containing tokens
3. **Token Rotation**: Implement token refresh mechanisms for long-lived applications
4. **Device Management**: Generate unique device IDs for each client installation
5. **Logout Handling**: Properly invalidate tokens on logout
### Example Secure Implementation
```javascript theme={null}
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
Detailed user authentication endpoints
Learn about API error responses