LivingAi
/
auth
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
auth/API_INTEGRATION.md

1232 lines
33 KiB
Markdown
Raw Blame History

# Farm Auth Service - API Integration Guide
Complete integration guide for Farm Auth Service with Kotlin Multiplatform Mobile (KMM) or Kotlin Native applications.
## Base URL
```
http://localhost:3000 (development)
https://your-domain.com (production)
```
## Table of Contents
- [Authentication Flow](#authentication-flow)
- [API Endpoints](#api-endpoints)
- [Kotlin Multiplatform Implementation](#kotlin-multiplatform-implementation)
- [Error Handling](#error-handling)
- [Security Best Practices](#security-best-practices)
- [Token Management](#token-management)
---
## Authentication Flow
1. **Request OTP** → User enters phone number
2. **Verify OTP** → User enters code, receives tokens + user info
3. **Use Access Token** → Include in `Authorization` header for protected endpoints
4. **Refresh Token** → When access token expires, get new tokens (auto-rotation)
5. **Logout** → Revoke refresh token on current device
6. **Device Management** → View/manage active devices
---
## API Endpoints
### 1. Request OTP
**Endpoint:** `POST /auth/request-otp`
**Request:**
```json
{
"phone_number": "+919876543210"
}
```
**Response (200):**
```json
{
"ok": true
}
```
**Error (400):**
```json
{
"error": "phone_number is required"
}
```
**Error (500):**
```json
{
"error": "Failed to send OTP"
}
```
**Phone Number Normalization:**
- `9876543210` → Automatically becomes `+919876543210` (10-digit assumed as Indian)
- `+919876543210` → Kept as is
- Phone numbers should ideally be in E.164 format with `+` prefix
---
### 2. Verify OTP
**Endpoint:** `POST /auth/verify-otp`
**Request:**
```json
{
"phone_number": "+919876543210",
"code": "123456",
"device_id": "android-installation-id-123",
"device_info": {
"platform": "android",
"model": "Samsung SM-M326B",
"os_version": "Android 14",
"app_version": "1.0.0",
"language_code": "en-IN",
"timezone": "Asia/Kolkata"
}
}
```
**Response (200):**
```json
{
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"phone_number": "+919876543210",
"name": null,
"role": "user",
"user_type": null
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"needs_profile": true,
"is_new_device": true,
"is_new_account": false,
"active_devices_count": 2
}
```
**Error (400):**
```json
{
"error": "phone_number and code are required"
}
```
or
```json
{
"error": "Invalid or expired OTP"
}
```
**Notes:**
- `device_id` is required and will be sanitized (must be 4-128 alphanumeric characters, otherwise hashed)
- `device_info` is optional but recommended for better device tracking
- `needs_profile` is `true` if `name` or `user_type` is null
- `is_new_device` indicates if this device was seen for the first time
- `is_new_account` indicates if the user account was just created
- `active_devices_count` shows how many active devices the user has
---
### 3. Refresh Token
**Endpoint:** `POST /auth/refresh`
**Request:**
```json
{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
**Response (200):**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
**Error (400):**
```json
{
"error": "refresh_token is required"
}
```
**Error (401):**
```json
{
"error": "Invalid refresh token"
}
```
**Important:**
- Refresh tokens **rotate on each use** - always save the new `refresh_token`
- Old refresh token is automatically revoked
- If refresh token is compromised and reused, all tokens for that device are revoked
---
### 4. Logout
**Endpoint:** `POST /auth/logout`
**Request:**
```json
{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
**Response (200):**
```json
{
"ok": true
}
```
**Note:** Returns `ok: true` even if token is already invalid (idempotent)
---
### 5. Get Current User Profile
**Endpoint:** `GET /users/me`
**Headers:**
```
Authorization: Bearer <access_token>
```
**Response (200):**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"phone_number": "+919876543210",
"name": "John Doe",
"role": "user",
"user_type": "seller",
"avatar_url": "https://example.com/avatar.jpg",
"language": "en",
"timezone": "Asia/Kolkata",
"created_at": "2024-01-15T10:30:00Z",
"last_login_at": "2024-01-20T14:22:00Z",
"active_devices_count": 2,
"location": {
"id": "location-uuid-here",
"country": "India",
"state": "Maharashtra",
"district": "Pune",
"city_village": "Pune City",
"pincode": "411001",
"coordinates": {
"latitude": 18.5204,
"longitude": 73.8567
},
"location_type": "home",
"is_saved_address": true,
"source_type": "manual",
"source_confidence": "high",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T14:22:00Z"
},
"locations": [
{
"id": "location-uuid-here",
"country": "India",
"state": "Maharashtra",
"district": "Pune",
"city_village": "Pune City",
"pincode": "411001",
"coordinates": {
"latitude": 18.5204,
"longitude": 73.8567
},
"location_type": "home",
"is_saved_address": true,
"source_type": "manual",
"source_confidence": "high",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T14:22:00Z"
}
]
}
```
**Response Notes:**
- `location`: Primary/most recent saved location (or `null` if no saved locations)
- `locations`: Array of all saved locations (empty array if none)
- `coordinates`: `null` if latitude/longitude not available
- All optional fields (`avatar_url`, `language`, `timezone`) may be `null`
**Response with No Saved Locations:**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"phone_number": "+919876543210",
"name": "John Doe",
"role": "user",
"user_type": "seller",
"avatar_url": null,
"language": null,
"timezone": null,
"created_at": "2024-01-15T10:30:00Z",
"last_login_at": "2024-01-20T14:22:00Z",
"active_devices_count": 1,
"location": null,
"locations": []
}
```
**Error (401):**
```json
{
"error": "Missing Authorization header"
}
```
or
```json
{
"error": "Invalid or expired token"
}
```
**Error (404):**
```json
{
"error": "User not found"
}
```
---
### 6. Update User Profile
**Endpoint:** `PUT /users/me`
**Headers:**
```
Authorization: Bearer <access_token>
```
**Request:**
```json
{
"name": "John Doe",
"user_type": "seller"
}
```
**Response (200):**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"phone_number": "+919876543210",
"name": "John Doe",
"role": "user",
"user_type": "seller"
}
```
**Valid `user_type` values:**
- `seller`
- `buyer`
- `service_provider`
**Error (400):**
```json
{
"error": "name and user_type are required"
}
```
---
### 7. List Active Devices
**Endpoint:** `GET /users/me/devices`
**Headers:**
```
Authorization: Bearer <access_token>
```
**Response (200):**
```json
{
"devices": [
{
"device_identifier": "android-installation-id-123",
"device_platform": "android",
"device_model": "Samsung SM-M326B",
"os_version": "Android 14",
"app_version": "1.0.0",
"language_code": "en-IN",
"timezone": "Asia/Kolkata",
"first_seen_at": "2024-01-15T10:30:00Z",
"last_seen_at": "2024-01-20T14:22:00Z",
"is_active": true
}
]
}
```
---
### 8. Logout Specific Device
**Endpoint:** `DELETE /users/me/devices/:device_id`
**Headers:**
```
Authorization: Bearer <access_token>
```
**Response (200):**
```json
{
"ok": true,
"message": "Device logged out successfully"
}
```
**Note:** This will:
- Mark the device as inactive in `user_devices`
- Revoke all refresh tokens for that device
- Log the action in `auth_audit`
---
### 9. Logout All Other Devices
**Endpoint:** `POST /users/me/logout-all-other-devices`
**Headers:**
```
Authorization: Bearer <access_token>
X-Device-Id: <current_device_id>
```
**Alternative:** Send `current_device_id` in request body:
```json
{
"current_device_id": "android-installation-id-123"
}
```
**Response (200):**
```json
{
"ok": true,
"message": "Logged out 2 device(s)",
"revoked_devices_count": 2
}
```
**Error (400):**
```json
{
"error": "current_device_id is required in header or body"
}
```
---
### 10. Health Check
**Endpoint:** `GET /health`
**Response (200):**
```json
{
"ok": true
}
```
Use this to verify the service is running before attempting authentication.
---
## Kotlin Multiplatform Implementation
### 1. Data Models (Common Module)
```kotlin
// commonMain/kotlin/models/Requests.kt
package com.farm.auth.models
import kotlinx.serialization.Serializable
@Serializable
data class RequestOtpRequest(val phone_number: String)
@Serializable
data class RequestOtpResponse(val ok: Boolean)
@Serializable
data class DeviceInfo(
val platform: String,
val model: String? = null,
@SerialName("os_version") val osVersion: String? = null,
@SerialName("app_version") val appVersion: String? = null,
@SerialName("language_code") val languageCode: String? = null,
val timezone: String? = null
)
@Serializable
data class VerifyOtpRequest(
@SerialName("phone_number") val phoneNumber: String,
val code: String,
@SerialName("device_id") val deviceId: String,
@SerialName("device_info") val deviceInfo: DeviceInfo? = null
)
@Serializable
data class Coordinates(
val latitude: Double,
val longitude: Double
)
@Serializable
data class Location(
val id: String,
val country: String?,
val state: String?,
val district: String?,
@SerialName("city_village") val cityVillage: String?,
val pincode: String?,
val coordinates: Coordinates?,
@SerialName("location_type") val locationType: String?,
@SerialName("is_saved_address") val isSavedAddress: Boolean,
@SerialName("source_type") val sourceType: String?,
@SerialName("source_confidence") val sourceConfidence: String?,
@SerialName("created_at") val createdAt: String,
@SerialName("updated_at") val updatedAt: String
)
@Serializable
data class User(
val id: String,
@SerialName("phone_number") val phoneNumber: String,
val name: String?,
val role: String,
@SerialName("user_type") val userType: String?,
@SerialName("avatar_url") val avatarUrl: String? = null,
val language: String? = null,
val timezone: String? = null,
@SerialName("created_at") val createdAt: String? = null,
@SerialName("last_login_at") val lastLoginAt: String? = null,
@SerialName("active_devices_count") val activeDevicesCount: Int? = null,
val location: Location? = null,
val locations: List<Location> = emptyList()
)
@Serializable
data class VerifyOtpResponse(
val user: User,
@SerialName("access_token") val accessToken: String,
@SerialName("refresh_token") val refreshToken: String,
@SerialName("needs_profile") val needsProfile: Boolean,
@SerialName("is_new_device") val isNewDevice: Boolean,
@SerialName("is_new_account") val isNewAccount: Boolean,
@SerialName("active_devices_count") val activeDevicesCount: Int
)
@Serializable
data class RefreshRequest(@SerialName("refresh_token") val refreshToken: String)
@Serializable
data class RefreshResponse(
@SerialName("access_token") val accessToken: String,
@SerialName("refresh_token") val refreshToken: String
)
@Serializable
data class LogoutRequest(@SerialName("refresh_token") val refreshToken: String)
@Serializable
data class LogoutResponse(val ok: Boolean)
@Serializable
data class UpdateProfileRequest(
val name: String,
@SerialName("user_type") val userType: String
)
@Serializable
data class Device(
@SerialName("device_identifier") val deviceIdentifier: String,
@SerialName("device_platform") val devicePlatform: String,
@SerialName("device_model") val deviceModel: String?,
@SerialName("os_version") val osVersion: String?,
@SerialName("app_version") val appVersion: String?,
@SerialName("language_code") val languageCode: String?,
val timezone: String?,
@SerialName("first_seen_at") val firstSeenAt: String,
@SerialName("last_seen_at") val lastSeenAt: String,
@SerialName("is_active") val isActive: Boolean
)
@Serializable
data class DevicesResponse(val devices: List<Device>)
@Serializable
data class LogoutAllOtherDevicesRequest(
@SerialName("current_device_id") val currentDeviceId: String
)
@Serializable
data class LogoutAllOtherDevicesResponse(
val ok: Boolean,
val message: String,
@SerialName("revoked_devices_count") val revokedDevicesCount: Int
)
@Serializable
data class ErrorResponse(val error: String)
@Serializable
data class HealthResponse(val ok: Boolean)
```
### 2. API Client (Common Module)
```kotlin
// commonMain/kotlin/network/AuthApiClient.kt
package com.farm.auth.network
import com.farm.auth.models.*
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.request.*
import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import kotlinx.serialization.json.Json
class AuthApiClient(
private val baseUrl: String,
private val httpClient: HttpClient
) {
private val json = Json {
ignoreUnknownKeys = true
isLenient = true
encodeDefaults = false
}
init {
httpClient.config {
install(ContentNegotiation) {
json(json)
}
}
}
suspend fun requestOtp(phoneNumber: String): Result<RequestOtpResponse> {
return try {
val response = httpClient.post("$baseUrl/auth/request-otp") {
contentType(ContentType.Application.Json)
setBody(RequestOtpRequest(phoneNumber))
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun verifyOtp(
phoneNumber: String,
code: String,
deviceId: String,
deviceInfo: DeviceInfo? = null
): Result<VerifyOtpResponse> {
return try {
val request = VerifyOtpRequest(phoneNumber, code, deviceId, deviceInfo)
val response = httpClient.post("$baseUrl/auth/verify-otp") {
contentType(ContentType.Application.Json)
setBody(request)
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun refreshToken(refreshToken: String): Result<RefreshResponse> {
return try {
val request = RefreshRequest(refreshToken)
val response = httpClient.post("$baseUrl/auth/refresh") {
contentType(ContentType.Application.Json)
setBody(request)
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun logout(refreshToken: String): Result<LogoutResponse> {
return try {
val request = LogoutRequest(refreshToken)
val response = httpClient.post("$baseUrl/auth/logout") {
contentType(ContentType.Application.Json)
setBody(request)
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun getCurrentUser(accessToken: String): Result<User> {
return try {
val response = httpClient.get("$baseUrl/users/me") {
contentType(ContentType.Application.Json)
header("Authorization", "Bearer $accessToken")
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun updateProfile(
name: String,
userType: String,
accessToken: String
): Result<User> {
return try {
val request = UpdateProfileRequest(name, userType)
val response = httpClient.put("$baseUrl/users/me") {
contentType(ContentType.Application.Json)
header("Authorization", "Bearer $accessToken")
setBody(request)
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun getDevices(accessToken: String): Result<DevicesResponse> {
return try {
val response = httpClient.get("$baseUrl/users/me/devices") {
contentType(ContentType.Application.Json)
header("Authorization", "Bearer $accessToken")
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun logoutDevice(
deviceId: String,
accessToken: String
): Result<LogoutResponse> {
return try {
val response = httpClient.delete("$baseUrl/users/me/devices/$deviceId") {
contentType(ContentType.Application.Json)
header("Authorization", "Bearer $accessToken")
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun logoutAllOtherDevices(
currentDeviceId: String,
accessToken: String
): Result<LogoutAllOtherDevicesResponse> {
return try {
val request = LogoutAllOtherDevicesRequest(currentDeviceId)
val response = httpClient.post("$baseUrl/users/me/logout-all-other-devices") {
contentType(ContentType.Application.Json)
header("Authorization", "Bearer $accessToken")
header("X-Device-Id", currentDeviceId)
setBody(request)
}
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
suspend fun healthCheck(): Result<HealthResponse> {
return try {
val response = httpClient.get("$baseUrl/health")
Result.success(response.body())
} catch (e: Exception) {
Result.failure(e)
}
}
}
```
### 3. Token Storage Interface (Common Module)
```kotlin
// commonMain/kotlin/storage/TokenStorage.kt
package com.farm.auth.storage
interface TokenStorage {
fun saveTokens(accessToken: String, refreshToken: String)
fun getAccessToken(): String?
fun getRefreshToken(): String?
fun clearTokens()
}
```
### 4. Android Token Storage Implementation
```kotlin
// androidMain/kotlin/storage/AndroidTokenStorage.kt
package com.farm.auth.storage
import android.content.Context
import android.content.SharedPreferences
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey
class AndroidTokenStorage(private val context: Context) : TokenStorage {
private val masterKey = MasterKey.Builder(context)
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
.build()
private val prefs: SharedPreferences = EncryptedSharedPreferences.create(
context,
"auth_tokens",
masterKey,
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)
override fun saveTokens(accessToken: String, refreshToken: String) {
prefs.edit().apply {
putString("access_token", accessToken)
putString("refresh_token", refreshToken)
apply()
}
}
override fun getAccessToken(): String? = prefs.getString("access_token", null)
override fun getRefreshToken(): String? = prefs.getString("refresh_token", null)
override fun clearTokens() {
prefs.edit().clear().apply()
}
}
```
### 5. iOS Token Storage Implementation (using Keychain)
```kotlin
// iosMain/kotlin/storage/IosTokenStorage.kt
package com.farm.auth.storage
import platform.Security.*
import platform.Foundation.*
class IosTokenStorage : TokenStorage {
private val accessTokenKey = "access_token"
private val refreshTokenKey = "refresh_token"
private val service = "com.farm.auth"
override fun saveTokens(accessToken: String, refreshToken: String) {
saveToKeychain(accessTokenKey, accessToken)
saveToKeychain(refreshTokenKey, refreshToken)
}
override fun getAccessToken(): String? = getFromKeychain(accessTokenKey)
override fun getRefreshToken(): String? = getFromKeychain(refreshTokenKey)
override fun clearTokens() {
deleteFromKeychain(accessTokenKey)
deleteFromKeychain(refreshTokenKey)
}
private fun saveToKeychain(key: String, value: String): Boolean {
val data = (value as NSString).dataUsingEncoding(NSUTF8StringEncoding) ?: return false
val query = mapOf(
kSecClass to kSecClassGenericPassword,
kSecAttrService to service,
kSecAttrAccount to key,
kSecValueData to data
)
SecItemDelete(query.toCFDictionary())
return SecItemAdd(query.toCFDictionary(), null) == errSecSuccess
}
private fun getFromKeychain(key: String): String? {
val query = mapOf(
kSecClass to kSecClassGenericPassword,
kSecAttrService to service,
kSecAttrAccount to key,
kSecReturnData to kCFBooleanTrue
)
val result = alloc<AnyVar>()
if (SecItemCopyMatching(query.toCFDictionary(), result.ptr) == errSecSuccess) {
val data = result.value as? NSData ?: return null
return NSString.create(data, NSUTF8StringEncoding) as String
}
return null
}
private fun deleteFromKeychain(key: String) {
val query = mapOf(
kSecClass to kSecClassGenericPassword,
kSecAttrService to service,
kSecAttrAccount to key
)
SecItemDelete(query.toCFDictionary())
}
}
```
### 6. Device Info Provider Interface
```kotlin
// commonMain/kotlin/device/DeviceInfoProvider.kt
package com.farm.auth.device
import com.farm.auth.models.DeviceInfo
interface DeviceInfoProvider {
fun getDeviceId(): String
fun getDeviceInfo(): DeviceInfo
}
```
### 7. Authentication Manager
```kotlin
// commonMain/kotlin/auth/AuthManager.kt
package com.farm.auth.auth
import com.farm.auth.models.*
import com.farm.auth.network.AuthApiClient
import com.farm.auth.storage.TokenStorage
import com.farm.auth.device.DeviceInfoProvider
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
class AuthManager(
private val apiClient: AuthApiClient,
private val tokenStorage: TokenStorage,
private val deviceInfoProvider: DeviceInfoProvider
) {
private val _currentUser = MutableStateFlow<User?>(null)
val currentUser: StateFlow<User?> = _currentUser.asStateFlow()
private val _isAuthenticated = MutableStateFlow(false)
val isAuthenticated: StateFlow<Boolean> = _isAuthenticated.asStateFlow()
suspend fun requestOtp(phoneNumber: String): Result<RequestOtpResponse> {
return apiClient.requestOtp(phoneNumber)
}
suspend fun verifyOtp(phoneNumber: String, code: String): Result<VerifyOtpResponse> {
val deviceId = deviceInfoProvider.getDeviceId()
val deviceInfo = deviceInfoProvider.getDeviceInfo()
return apiClient.verifyOtp(phoneNumber, code, deviceId, deviceInfo)
.onSuccess { response ->
tokenStorage.saveTokens(response.accessToken, response.refreshToken)
_currentUser.value = response.user
_isAuthenticated.value = true
}
}
suspend fun refreshTokens(): Result<Pair<String, String>> {
val refreshToken = tokenStorage.getRefreshToken()
?: return Result.failure(Exception("No refresh token"))
return apiClient.refreshToken(refreshToken)
.onSuccess { response ->
tokenStorage.saveTokens(response.accessToken, response.refreshToken)
}
.onFailure {
// If refresh fails, clear tokens and logout
if (it.message?.contains("Invalid refresh token") == true) {
logout()
}
}
.map { it.accessToken to it.refreshToken }
}
suspend fun logout() {
tokenStorage.getRefreshToken()?.let { refreshToken ->
apiClient.logout(refreshToken)
}
tokenStorage.clearTokens()
_currentUser.value = null
_isAuthenticated.value = false
}
suspend fun getCurrentUser(): Result<User> {
val accessToken = tokenStorage.getAccessToken()
?: return Result.failure(Exception("Not authenticated"))
return apiClient.getCurrentUser(accessToken)
.onSuccess { user ->
_currentUser.value = user
}
.recoverCatching { error ->
if (error.message?.contains("401") == true ||
error.message?.contains("Unauthorized") == true) {
// Try to refresh token and retry
refreshTokens().getOrNull()?.let { (newAccessToken, _) ->
apiClient.getCurrentUser(newAccessToken)
.onSuccess { user ->
_currentUser.value = user
}
} ?: Result.failure(error)
} else {
Result.failure(error)
}
}
}
suspend fun updateProfile(name: String, userType: String): Result<User> {
val accessToken = tokenStorage.getAccessToken()
?: return Result.failure(Exception("Not authenticated"))
return apiClient.updateProfile(name, userType, accessToken)
.onSuccess { user ->
_currentUser.value = user
}
}
suspend fun getDevices(): Result<DevicesResponse> {
val accessToken = tokenStorage.getAccessToken()
?: return Result.failure(Exception("Not authenticated"))
return callWithAuth { token ->
apiClient.getDevices(token)
}
}
suspend fun logoutDevice(deviceId: String): Result<LogoutResponse> {
return callWithAuth { token ->
apiClient.logoutDevice(deviceId, token)
}
}
suspend fun logoutAllOtherDevices(): Result<LogoutAllOtherDevicesResponse> {
val currentDeviceId = deviceInfoProvider.getDeviceId()
return callWithAuth { token ->
apiClient.logoutAllOtherDevices(currentDeviceId, token)
}
}
fun getAccessToken(): String? = tokenStorage.getAccessToken()
private suspend fun <T> callWithAuth(
block: suspend (String) -> Result<T>
): Result<T> {
val token = tokenStorage.getAccessToken()
?: return Result.failure(Exception("Not authenticated"))
return block(token).recoverCatching { error ->
if (error.message?.contains("401") == true ||
error.message?.contains("Unauthorized") == true) {
// Token expired, refresh and retry
refreshTokens().getOrNull()?.let { (newAccessToken, _) ->
block(newAccessToken)
} ?: Result.failure(Exception("Failed to refresh token"))
} else {
Result.failure(error)
}
}
}
}
```
---
## Error Handling
### Common Error Codes
| Status | Error | Description |
|--------|-------|-------------|
| 400 | `phone_number is required` | Missing phone number in request |
| 400 | `Invalid or expired OTP` | Wrong code, OTP expired (10 min), or max attempts exceeded (5) |
| 400 | `name and user_type are required` | Missing required fields in profile update |
| 400 | `current_device_id is required` | Missing device ID for logout all devices |
| 401 | `Invalid refresh token` | Token expired, revoked, or compromised |
| 401 | `Missing Authorization header` | Access token not provided |
| 401 | `Invalid or expired token` | Access token invalid or expired |
| 404 | `User not found` | User account doesn't exist |
| 403 | `Origin not allowed` | CORS restriction (production only) |
| 500 | `Internal server error` | Server-side error |
| 500 | `Failed to send OTP` | Twilio SMS sending failed |
### Error Response Format
```json
{
"error": "Error message here"
}
```
---
## Security Best Practices
1. **Store tokens securely**
- **Android**: Use `EncryptedSharedPreferences` (Android Security Library)
- **iOS**: Use Keychain Services
- Never store tokens in plain SharedPreferences/UserDefaults
2. **Handle token expiration**
- Automatically refresh when access token expires (401 response)
- Implement retry logic with token refresh
3. **Rotate refresh tokens**
- Always save the new `refresh_token` after refresh
- Old refresh tokens are automatically revoked
4. **Validate device_id**
- Use consistent device identifier (Android ID, Installation ID, or Vendor ID)
- Device ID should be 4-128 alphanumeric characters
- Server will hash invalid device IDs
5. **Handle reuse detection**
- If refresh returns 401 with "Invalid refresh token", force re-login
- This indicates potential token compromise
6. **Secure network communication**
- Always use HTTPS in production
- Implement certificate pinning if needed
7. **Rate limiting awareness**
- Don't spam OTP requests
- Implement client-side rate limiting if possible
---
## Token Management
### Token Expiration
- **Access Token:** 15 minutes (default, configurable via `JWT_ACCESS_TTL` env var)
- **Refresh Token:** 7 days (default, configurable via `JWT_REFRESH_TTL` env var)
- **Refresh Token Idle Timeout:** 3 days (default, configurable via `REFRESH_MAX_IDLE_MINUTES` = 4320)
- **OTP:** 10 minutes (fixed)
### Auto-refresh Pattern
```kotlin
suspend fun <T> callWithAuth(
block: suspend (String) -> Result<T>
): Result<T> {
val token = tokenStorage.getAccessToken()
?: return Result.failure(Exception("Not authenticated"))
return block(token).recoverCatching { error ->
if (error.message?.contains("401") == true ||
error.message?.contains("Unauthorized") == true) {
// Token expired, refresh and retry
refreshTokens().getOrNull()?.let { (newAccessToken, _) ->
block(newAccessToken)
} ?: Result.failure(Exception("Failed to refresh token"))
} else {
Result.failure(error)
}
}
}
```
---
## Notes
- Phone numbers are auto-normalized: 10-digit numbers → `+91` prefix
- Device ID should be 4-128 alphanumeric characters (server sanitizes if invalid)
- Refresh tokens rotate on each use - always update stored token
- If `needs_profile: true`, prompt user to complete profile before accessing app
- `is_new_device` and `is_new_account` flags help with onboarding flows
- Device management endpoints require authentication
- All timestamps are in ISO 8601 format with timezone (UTC)
---
## Example Usage (Android Activity)
```kotlin
class LoginActivity : AppCompatActivity() {
private lateinit var authManager: AuthManager
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val httpClient = HttpClient(Android) {
install(ContentNegotiation) {
json()
}
}
val apiClient = AuthApiClient("http://your-api-url", httpClient)
val tokenStorage = AndroidTokenStorage(this)
val deviceInfoProvider = AndroidDeviceInfoProvider(this)
authManager = AuthManager(apiClient, tokenStorage, deviceInfoProvider)
// Observe authentication state
lifecycleScope.launch {
authManager.isAuthenticated.collect { isAuth ->
if (isAuth) {
// Navigate to main screen
}
}
}
}
private fun requestOtp() {
lifecycleScope.launch {
val phoneNumber = phoneInput.text.toString()
authManager.requestOtp(phoneNumber)
.onSuccess {
showToast("OTP sent!")
}
.onFailure {
showError(it.message ?: "Failed to send OTP")
}
}
}
private fun verifyOtp() {
lifecycleScope.launch {
val phoneNumber = phoneInput.text.toString()
val code = otpInput.text.toString()
authManager.verifyOtp(phoneNumber, code)
.onSuccess { response ->
if (response.needsProfile) {
startActivity(Intent(this@LoginActivity, ProfileSetupActivity::class.java))
} else {
startActivity(Intent(this@LoginActivity, MainActivity::class.java))
}
finish()
}
.onFailure {
showError("Invalid OTP")
}
}
}
}
```
Reference in New Issue View Git Blame Copy Permalink