Skip to content

CONTRACT.md

Latest commit

 

History

History
177 lines (133 loc) · 6.09 KB

CONTRACT.md

File metadata and controls

177 lines (133 loc) · 6.09 KB
Raw

Send OTP

Documentation | Technical details | Add Twilio

Receive an encrypted SMS or voice request from Microsoft Entra ID.
Method POST
Path /api/SendOtp
Authentication Easy Auth
Content type application/json

Important

Easy Auth must validate the approved Microsoft caller before the Function runs. The encrypted payload protects request data. It does not authenticate the caller.

Authentication

Configure Easy Auth with:

  • HTTPS required.
  • Unauthenticated requests returned as 401.
  • The endpoint application audience.
  • The trusted tenant issuer.
  • A nonempty allowlist for the approved Microsoft caller.

See the Easy Auth checklist.

HTTP request

POST https://<function-host>/api/SendOtp
Content-Type: application/json
Authorization: Bearer <access-token>

Request headers

Header Value
Authorization Required bearer token. Easy Auth consumes it.
Content-Type Required. Use application/json.
x-ms-correlation-id Optional correlation fallback.
x-ms-client-request-id Optional request identifier.

The Function does not forward the bearer token to the phone provider.

Request body

  • type — Required string. Use microsoft.mfa.otpDeliver.v1.
  • channel — Required integer or string. 1 or "sms" for SMS. 2 or "voice" for voice.
  • mode — Required integer or string. 1 or "live" to send. 2 or "evaluation" for no-send validation.
  • encryptedDeliveryContext — Required compact JWE string.
  • tenantId — Optional routing metadata.
  • correlationId — Optional sign-in correlation value.
  • ttlSeconds — Optional positive integer up to 2147483647.

Send integer channel, mode, and TTL values in their documented forms for consistent behavior across all runtimes. See request validation and runtime differences.

Encrypted delivery context

The JWE uses RSA-OAEP-256 and A256GCM. After decryption, the JSON contains:

  • nonce — Required. Returned unchanged after evaluation or provider acceptance.
  • phoneNumber — Required phone number.
  • message — Required localized message containing the passcode.
  • otp — Optional string containing the separate six-digit passcode. Preserve leading zeros.
  • locale — Optional voice locale.
  • extension — Optional office-voice data.
  • riskContext — Optional JSON object containing arbitrary risk fields; may be null.
  • textToVoice — Optional legacy speech data.

Microsoft Entra ID supplies otp for SMS and voice, with a generated test code in evaluation mode. It belongs inside the encrypted delivery context, not the outer request body. Requests that omit it or set it to null remain supported.

riskContext has no fixed field schema. Unknown keys, nested objects and arrays, and values such as false, 0, and null are preserved. Missing fields are not filled with defaults.

See JWE validation and key handling for limits, algorithms, key settings, and runtime behavior.

Modes

  • Evaluation: validates authentication, the envelope, and decryption. It returns the nonce without reading provider credentials or sending a message.
  • Live: sends through the configured provider and returns success after recognized provider acceptance.

Provider acceptance is not proof of recipient delivery.

Response

If successful, the endpoint returns 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "nonce": "<decrypted nonce>",
  "correlationId": "<correlation value>",
  "providerStatus": "accepted"
}
Field Description
nonce Original decrypted nonce.
correlationId Request correlation value or generated fallback.
providerStatus "accepted" for evaluation or recognized live acceptance.

Failures omit nonce and providerStatus.

HTTP status codes

Status Description
200 OK Evaluation completed or the provider accepted the request.
400 Bad Request Invalid request or encrypted content.
401 Unauthorized Caller or provider authentication failed.
403 Forbidden Caller access was denied or the provider blocked the request.
429 Too Many Requests Provider throttling.
502 Bad Gateway Provider configuration, network, or response failure.
504 Gateway Timeout Provider request timed out.

Check a timed-out live request before retrying. The provider might already have accepted it.

Related guidance