SMS Auth Endpoints
API reference for SMS OTP authentication endpoints. These endpoints allow end users to authenticate using their phone number and a one-time verification code sent via SMS.
All endpoints require Content-Type: application/json and an Authorization: Bearer <api_key> header. The project is resolved automatically from the API key.
Send code
Send a 6-digit verification code to a phone number via SMS.
Request body
- Name
phone- Type
- string
- Description
The user's phone number. Will be normalized to E.164 format.
- Name
callback_url- Type
- string
- Description
A registered callback URL for the project.
The project is resolved automatically from the API key in the Authorization header.
Response 200
{
"success": true
}
This endpoint always returns 200 with { "success": true } when the phone is rate-limited, to prevent phone number enumeration.
Error responses
| Status | Error |
|---|---|
400 | Invalid phone number |
401 | Missing or invalid API key |
403 | Callback URL not registered or SMS provider not enabled |
404 | Project not found |
415 | Invalid Content-Type |
429 | Rate limited (IP-based) |
500 | SMS delivery failed |
Rate limits
- 2 per 10 minutes per IP address
- 3 per 30 minutes per phone number per project (silent — returns 200)
Verify code
Verify a 6-digit OTP code and authenticate the user. Creates the user on first verification.
Request body
- Name
phone- Type
- string
- Description
The user's phone number (must match the number used in send-code).
- Name
code- Type
- string
- Description
The 6-digit verification code received via SMS.
- Name
callback_url- Type
- string
- Description
A registered callback URL for the project.
Response 200
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "user_abc123",
"phone": "+15551234567",
"email": null,
"name": null,
"phone_verified": true
}
}
Error responses
| Status | Error |
|---|---|
400 | Invalid phone number or code format |
401 | Invalid or expired code, or missing/invalid API key |
403 | Callback URL not registered or SMS provider not enabled |
404 | Project not found |
415 | Invalid Content-Type |
429 | Rate limited |
Rate limits
- 5 per 15 minutes per IP address
JWT claims
{
"sub": "user_abc123",
"phone": "+15551234567",
"email": null,
"name": null,
"picture": null,
"provider": "sms",
"phone_verified": true,
"project_id": "proj_xyz",
"iss": "authgate",
"exp": 1234567890,
"iat": 1234567590
}
The provider field is always "sms" and phone_verified is always true (only set on successful verification).