Authentication
Learn how to authenticate with the VoiceStamp API using Bearer tokens
Two-Tier Authentication System
VoiceStamp uses a two-tier authentication system:
- User Session Tokens: Generated per-user login (expires after 30 days)
- Static API Token: Fallback service-level token (always valid)
Getting Started
All API requests must include an Authorization header with a Bearer token:
Authorization: Bearer YOUR_TOKEN_HEREAuthentication Flow
1. Login with Email
Start the authentication process by sending the user's email address:
POST /api/v1/auth/login
{
"email": "user@example.com"
}Response
{
"success": true,
"message": "Verification code sent to email"
}2. Verify Code
The user will receive a 6-digit verification code. Verify it to get the session token:
POST /api/v1/auth/verify-code
{
"email": "user@example.com",
"code": "123456"
}Response
{
"success": true,
"data": {
"token": "user_session_token_here",
"user": {
"id": "uuid",
"email": "user@example.com",
"name": "John Doe"
},
"expires_at": "2025-10-23T10:30:00Z"
}
}Using Tokens
Frontend Implementation
Each frontend project should store tokens in project-specific localStorage keys:
// React SuperAdmin
const token = localStorage.getItem('voicestamp_admin_token') ||
process.env.VITE_WEBSITE_API_TOKEN;
// VoiceStamp v2 Mobile
const token = localStorage.getItem('voicestamp_v2_token') ||
process.env.VITE_WEBSITE_API_TOKEN;
// Next.js Website
const token = localStorage.getItem('voicestamp_website_token') ||
process.env.NEXT_PUBLIC_WEBSITE_API_TOKEN;
// API Request
const response = await fetch('/api/v1/endpoint', {
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
});Error Handling
Handle 401 responses by clearing user tokens and falling back to static token:
if (response.status === 401 && userToken) {
// Clear expired user token
localStorage.removeItem('project_specific_token');
// Retry with static API token
const fallbackResponse = await fetch('/api/v1/endpoint', {
headers: {
'Authorization': `Bearer ${STATIC_API_TOKEN}`,
'Content-Type': 'application/json'
}
});
}Environment Configuration
Backend (Laravel)
# .env
WEBSITE_API_TOKEN=your_static_api_token_hereFrontend Projects
# React SuperAdmin (.env)
VITE_WEBSITE_API_TOKEN=your_static_api_token_here
VITE_API_BASE_URL=https://voicestamp.vps.webdock.cloud/api/v1
# Next.js Website (.env.local)
NEXT_PUBLIC_WEBSITE_API_TOKEN=your_static_api_token_here
NEXT_PUBLIC_API_BASE_URL=https://voicestamp.vps.webdock.cloud/api/v1Security Best Practices
- Never hardcode API tokens in source code
- Use environment variables for configuration
- Store user tokens in project-specific localStorage keys
- Handle token expiration gracefully with fallbacks
- Use HTTPS for all production API calls
- Rotate tokens periodically for security
Token Validation
You can validate any token using the verification endpoint:
GET /api/v1/auth/verify
Headers: Authorization: Bearer YOUR_TOKEN
Response
{
"valid": true,
"user": {
"id": "uuid",
"email": "user@example.com",
"role": "user"
},
"expires_at": "2025-10-23T10:30:00Z"
}