Skip to main content
POST
/
api
/
auth
/
send-otp
curl -X POST https://api.masareagle.com/api/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+966501234567"
  }'

{
  "message": "تم إرسال رمز التحقق بنجاح",
  "expiresAt": "2026-03-10T15:35:00Z",
  "code": "123456"
}

​
Overview

This endpoint generates and sends a one-time password (OTP) to the specified phone number via SMS. The OTP is valid for 5 minutes and can be used with the /connect/token endpoint to authenticate users.

​
Authentication

This endpoint does not require authentication.

​
Request Body

​
phoneNumber
string
required
The phone number to send the OTP to. Must include country code with + prefix (e.g., +966501234567).Validation rules:
  • Must start with +
  • Length must be between 9 and 16 digits (including country code)
  • Only digits allowed after the + symbol

​
Response

​
message
string
Success message in Arabic: “تم إرسال رمز التحقق بنجاح” (OTP sent successfully)
​
expiresAt
string
ISO 8601 timestamp indicating when the OTP expires (5 minutes from generation)
​
code
string
The OTP code (6 digits). This field is only returned in development/testing environments.
curl -X POST https://api.masareagle.com/api/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+966501234567"
  }'

{
  "message": "تم إرسال رمز التحقق بنجاح",
  "expiresAt": "2026-03-10T15:35:00Z",
  "code": "123456"
}

​
Implementation Details

The endpoint:
  1. Validates the phone number format according to Identity.Core.ValueObjects.PhoneNumber rules
  2. Generates a 6-digit OTP code using cryptographic random number generation
  3. Stores the OTP in the database with a 5-minute expiration
  4. Sends the OTP via SMS using the configured SMS provider (Taqnyat)
  5. Returns the expiration time to the client

​
Use Cases

  • Driver Authentication: Drivers use this endpoint to receive an OTP for passwordless login
  • Passenger Authentication: Passengers authenticate using their phone number and OTP
  • Account Recovery: Users can regain access to their account using their registered phone number

​
Next Steps

After receiving the OTP:
  1. User enters the OTP code in your application
  2. Call the Token endpoint with grant type urn:masareagle:otp to exchange the OTP for access and refresh tokens
  3. Use the access token to authenticate subsequent API requests
  • Resend OTP - Resend OTP if not received or expired
  • Token - Exchange OTP for access tokens

​
Source Code Reference

  • Endpoint: src/services/Identity/src/Identity.Web/AuthEndpoints.cs:12
  • Command: src/services/Identity/src/Identity.UseCases/Auth/SendOtp/SendOtpCommand.cs
  • Phone Validation: src/services/Identity/src/Identity.Core/ValueObjects/PhoneNumber.cs

Build docs developers (and LLMs) love

Get started for freeTalk to us