Skip to main content

​
Authentication Process

  1. Sign In: POST /auth/signin with phone → get accessToken
  2. Create OTP: POST /auth/otp/create → OTP sent via SMS
  3. Validate OTP: POST /auth/otp/validate with OTP → get sessionToken
  4. API Calls: Use sessionToken in Authorization header

​
Endpoints

​
Sign In

POST /auth/signin
{
  "phoneNumber": "+1234567890"
}

​
Create OTP

POST /auth/otp/create
Authorization: Bearer ACCESS_TOKEN

​
Validate OTP

POST /auth/otp/validate
Authorization: Bearer ACCESS_TOKEN
{
  "otp": "123456"
}

​
Sign Out

POST /auth/signout
Authorization: Bearer SESSION_TOKEN

​
Implementation (React Native)

import AsyncStorage from '@react-native-async-storage/async-storage';

// 1. Sign in
const { user, accessToken } = await fetch('/api/v1/auth/signin', {
  method: 'POST',
  body: JSON.stringify({ phoneNumber })
}).then(r => r.json());
await AsyncStorage.setItem('accessToken', accessToken);

// 2. Create OTP
await fetch('/api/v1/auth/otp/create', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

// 3. Validate OTP
const { sessionToken } = await fetch('/api/v1/auth/otp/validate', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({ otp })
}).then(r => r.json());
await AsyncStorage.setItem('sessionToken', sessionToken);

// 4. Make authenticated requests
const data = await fetch('/api/v1/users/current', {
  headers: { 'Authorization': `Bearer ${sessionToken}` }
}).then(r => r.json());

​
Security Features

  • Phone number validation (E.164 format)
  • OTP expires in 5 minutes
  • Single-use OTP codes
  • Rate limiting on OTP requests

​
Error Codes

  • VALIDATION_ERROR: Invalid phone format
  • OTP_EXPIRED: OTP has expired
  • INVALID_OTP: Wrong OTP code
  • RATE_LIMITED: Too many requests