Web Auth - Usage Examples
Last Updated: 2026-07-09
Overview
web_auth uses session-based authentication (cookies), not bearer tokens. There is no Authorization header for these endpoints; the session cookie is set on login and sent with each subsequent request. All endpoints are mounted under /auth/ at the application root (no /api/ prefix).
Dashboard Login Flow (Password)
Step 1: Check email to determine auth path
curl -s -X POST https://api.djanity.com/auth/check-email/ \
-H "Content-Type: application/json" \
-c cookies.txt \
-d '{"email": "[email protected]", "session_type": "dashboard"}'
Response: user has a password:
{
"action": "password_login",
"has_password": true,
"user_exists": true,
"message": "Enter your password"
}
Response: user has no password (OTP path):
{
"action": "send_otp",
"has_password": false,
"user_exists": true,
"message": "Verify your email to set a password"
}
Step 2a: Password login
curl -s -X POST https://api.djanity.com/auth/login/ \
-H "Content-Type: application/json" \
-c cookies.txt -b cookies.txt \
-d '{
"email": "[email protected]",
"password": "SecurePass123!",
"session_type": "dashboard"
}'
Response (200 OK):
{
"success": true,
"session_type": "dashboard",
"user": {
"id": "user-uuid-here",
"email": "[email protected]",
"name": "Jane Smith",
"roles": ["store_manager"],
"primary_role": "store_manager"
},
"session": {
"id": "session-uuid-here",
"session_type": "dashboard",
"expires_at": "2026-07-16T14:00:00Z"
}
}
Response: invalid password (401):
{"error": "Invalid password"}
Response: account locked (429):
{"error": "Account temporarily locked due to suspicious activity. Try again in 15 minutes."}
OTP Login Flow
Step 2b: Initiate OTP login (no password field)
curl -s -X POST https://api.djanity.com/auth/login/ \
-H "Content-Type: application/json" \
-c cookies.txt \
-d '{"email": "[email protected]", "session_type": "dashboard"}'
Response:
{
"success": true,
"message": "Verification code sent to [email protected]",
"email": "[email protected]"
}
Step 3: Verify OTP
curl -s -X POST https://api.djanity.com/auth/verify-otp/ \
-H "Content-Type: application/json" \
-c cookies.txt -b cookies.txt \
-d '{
"email": "[email protected]",
"otp_code": "482917",
"session_type": "dashboard"
}'
Response: user has password (session created):
{
"success": true,
"session_type": "dashboard",
"user": {"id": "user-uuid-here", "email": "[email protected]"},
"session": {"id": "session-uuid-here", "expires_at": "2026-07-16T14:00:00Z"}
}
Response: user has no password (prompt to create one):
{
"success": true,
"action": "create_password",
"message": "Set a password to skip verification next time",
"email": "[email protected]"
}
Response: invalid OTP (400):
{"error": "Invalid or expired verification code"}
Step 3b: Set a password (first-time users)
curl -s -X POST https://api.djanity.com/auth/set-password/ \
-H "Content-Type: application/json" \
-c cookies.txt -b cookies.txt \
-d '{
"email": "[email protected]",
"password": "NewSecurePass123!",
"session_type": "dashboard"
}'
Response (200 OK):
{
"success": true,
"message": "Password created successfully",
"session_type": "dashboard",
"user": {"id": "user-uuid-here", "email": "[email protected]"},
"session": {"id": "session-uuid-here", "expires_at": "2026-07-16T14:00:00Z"}
}
Password Recovery
Step 1: Request recovery code
curl -s -X POST https://api.djanity.com/auth/forgot-password/ \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]"}'
Response:
{
"success": true,
"message": "Recovery code sent to [email protected]"
}
Step 2: Validate the recovery code (non-consuming)
curl -s -X POST https://api.djanity.com/auth/verify-recovery-otp/ \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "otp_code": "739204"}'
Response:
{"success": true, "message": "Recovery code is valid"}
Step 3: Reset the password (consumes the OTP)
curl -s -X POST https://api.djanity.com/auth/reset-password/ \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"otp_code": "739204",
"new_password": "FreshNewPass456!"
}'
Response:
{
"success": true,
"message": "Password reset successfully. You can now log in with your new password."
}
Session Management
Check session status
curl -s https://api.djanity.com/auth/session/ \
-b cookies.txt
Response: authenticated:
{
"authenticated": true,
"session_type": "dashboard",
"is_guest": false,
"session": {
"id": "session-uuid-here",
"session_type": "dashboard",
"expires_at": "2026-07-16T14:00:00Z",
"last_activity": "2026-07-09T14:00:00Z"
},
"user": {
"id": "user-uuid-here",
"email": "[email protected]",
"name": "Jane Smith",
"roles": ["store_manager"],
"primary_role": "store_manager"
},
"permissions": [
{
"session_type": "dashboard",
"endpoint_pattern": "^/api/products/$",
"http_methods": ["GET", "POST"],
"description": "Manage products"
}
]
}
Response: not authenticated:
{"authenticated": false}
Log out
curl -s -X POST https://api.djanity.com/auth/logout/ \
-b cookies.txt
Response:
{"success": true, "message": "Logged out successfully"}
Customer Registration
Step 1: Initiate registration
curl -s -X POST https://api.djanity.com/auth/register/initiate/ \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe"
}'
Response:
{
"success": true,
"registration_token": "reg_A8xK2pQz9vL3mN7",
"message": "Verification code sent to [email protected]",
"is_existing_user": false,
"action": "register"
}
Step 2: Verify and complete registration
curl -s -X POST https://api.djanity.com/auth/register/verify/ \
-H "Content-Type: application/json" \
-c cookies.txt -b cookies.txt \
-d '{
"email": "[email protected]",
"otp_code": "614829",
"registration_token": "reg_A8xK2pQz9vL3mN7"
}'
Response:
{
"success": true,
"user": {
"id": "new-user-uuid",
"email": "[email protected]",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe"
},
"session": {"id": "session-uuid-here", "session_type": "dashboard"},
"profile_complete": false,
"missing_fields": ["name", "phone"]
}
Step 3 (if needed): Resend the OTP
curl -s -X POST https://api.djanity.com/auth/register/resend-otp/ \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"registration_token": "reg_A8xK2pQz9vL3mN7"
}'
Response:
{"success": true, "message": "Verification code resent to [email protected]", "expires_in": 300}