Skip to Content

SMS OTP

Auris uses SMS one-time codes for phone verification and supported second-factor flows. Start by checking the tenant’s enabled authentication methods and SMS delivery configuration.

SMS 2FA cannot be enabled while magic-link login is enabled: the enable endpoint returns 409 SMS_2FA_UNAVAILABLE. Do not disable a tenant’s existing login method merely to follow this example. Choose the authentication policy first and test it in a separate environment.

Prerequisites

  • A tenant with SMS OTP enabled and a configured SMS delivery provider.
  • An authenticated user for phone enrollment and SMS 2FA settings.
  • A phone number in E.164 format controlled by that user.
  • A supported login flow and a recovery process agreed with the tenant administrator.

This guide does not document an unauthenticated phone-number-only passwordless login endpoint. The old /api/user/phone/send-otp and /api/user/phone/verify-otp paths are not the enrollment endpoints below.

Phone Number Management

Use the authenticated user context and tenant binding required by your integration.

RequestBodyResult
POST /api/user/phone/set{ phoneNumber: string }Sets the number and attempts to send its verification code
POST /api/user/phone/verify{ code: string }Verifies the code and marks the number verified on success
GET /api/user/phoneNoneReads the user’s phone and verification state

A send response can be HTTP 200 with success: false. Check the body, not only the HTTP status.

async function postPhoneAction(path, body) {
  const response = await fetch(new URL(path, apiOrigin), {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'x-tenant': tenantRealm,
    },
    body: JSON.stringify(body),
  })
  const result = await response.json()
  if (!response.ok || result.success !== true) {
    throw new Error('Phone action failed; inspect the response privately')
  }
  return result
}
 
// Run each step after the corresponding user interaction.
await postPhoneAction('/api/user/phone/set', { phoneNumber })
// Prompt the user for the delivered code before continuing.
await postPhoneAction('/api/user/phone/verify', { code: userEnteredCode })

Do not log the phone number, OTP or bearer token. The example leaves UI, recovery, rate-limit handling and secure credential storage to your application.

SMS as Two-Factor Authentication (2FA)

After phone ownership is verified and the tenant policy permits SMS 2FA:

  1. Enable it with POST /api/user/2fa/sms/enable in the authenticated user context.
  2. During a supported challenge flow, request a code through POST /api/user/2fa/sms/send. This requires a verified bearer credential; the route also accepts the restricted pending step-up credential used by hosted login.
  3. Complete the challenge through hosted login. The verification route is POST /api/auth/verify-2fa, with the flow’s email, code, method and bearer context. A pending credential is not an authenticated application session.
  4. Disable SMS 2FA through the authenticated settings flow backed by POST /api/user/2fa/sms/disable.

Prefer the hosted login integration to assembling challenge steps independently.

Rate Limits

Service ruleCurrent value
Numeric code length6 digits
Code validity5 minutes
Send cooldown for the user, tenant and purpose30 seconds
Send rate limit5 sends per user per hour
Maximum verification attempts per code5

Handle success, message and cooldownSeconds where returned. Do not assume every failure uses HTTP 429 or includes Retry-After. Test delivery failure, repeated sends, wrong codes, expiration and replay before rollout.

Security Considerations

SMS delivery can fail, and account access can be affected by SIM-swap attacks. Evaluate passkeys or an authenticator according to your threat model. A successful OTP verifies the corresponding challenge; it does not grant access to every tenant or resource.

Read the MFA guide and authentication settings. For help selecting a supported enrollment and recovery flow, request an Auris integration demo .

Architecture