How can we help you?

Advanced documentation search

Issue an email or SMS authentication challenge

Product: FeraAuth Topic: API Versions: Applies to all documented versions Current
Written by user
Updated

Audience: Application developers
Editorial status: Published — Source Validated
Product: FeraAuth
Classification: public

POST /api/v1/auth/challenge/send

Overview

Implements controller.sendChallenge in routes/api/v1/auth/routes.js:31. This public identity boundary applies the documented field validation, safe credential responses, source-IP checks, rate limits, and delivery behavior without requiring an existing session.

Deprecated compatibility paths

  • POST /api/auth/challenge/send

Use the versioned canonical path for new integrations.

Authentication and access

This operation does not require ordinary bearer authentication.

Control Contract
Authentication public
Authorization No prior grant is required; the handler applies credential, token, challenge, rate-limit, or safe-disclosure checks.
Licensing FeraAuth does not evaluate product licenses; consuming products establish access by provisioning FeraAuth instance assignments and permissions.
Instance Context No licensed tenant context is required; this identity bootstrap or public instance-discovery operation uses only its documented inputs.
Ownership No customer-owned resource is selected before authentication; safe-disclosure behavior prevents identity enumeration where applicable.

Parameters

No operation parameters.

Request body

JSON identity command consumed by the source-traced handler.

application/json

Schema: ChallengeRequest

{
    "email": "developer@example.com",
    "channel": "email"
}

Example request

cURL

curl --request POST \ \
  --url 'https://auth.feradel.com/api/v1/auth/challenge/send' \
  --header 'content-type: application/json' \
  --data '{"email":"developer@example.com","channel":"email"}'

Responses

200 The challenge was persisted and delivered by email or SMS.

Content type: application/json; schema: ChallengeReceipt

{
    "success": true,
    "sent": "2026-08-25T14:00:00.000Z",
    "expires": "2026-08-25T14:10:00.000Z",
    "token": "715c9ebb-0470-11f1-a928-0ed2cd1b87df"
}

400 Email, channel, phone, account, or request fields are invalid.

Content type: application/json; schema: AuthError

{
    "success": false,
    "error": {
        "status": 400,
        "message": "Invalid credentials"
    }
}

429 A challenge was issued for the account less than 30 seconds ago.

Content type: application/json; schema: AuthError

{
    "success": false,
    "error": {
        "status": 429,
        "message": "Too many requests"
    }
}

502 Email or SMS delivery failed and the undelivered challenge was cleared.

Content type: application/json; schema: AuthError

{
    "success": false,
    "error": {
        "status": 502,
        "message": "Unable to complete request"
    }
}

Status and retry matrix

Status Condition Retryable Developer action
200 The challenge was persisted and delivered by email or SMS. No Continue with the returned identity representation.
400 Email, channel, phone, account, or request fields are invalid. No Correct the documented credential, permission, state, or dependency condition before retrying.
429 A challenge was issued for the account less than 30 seconds ago. Yes Wait at least 30 seconds before requesting another challenge.
502 Email or SMS delivery failed and the undelivered challenge was cleared. Yes Correct the documented credential, permission, state, or dependency condition before retrying.

Related operations and events

  • Operation auth_post_authChallengePre
  • Operation auth_post_authChallengeVerify
  • Operation auth_get_authVerifySession
  • Operation auth_post_authCaldavVerify
  • Operation auth_post_authVerifyToken
  • Operation auth_post_authLocal
  • Operation auth_post_auth
  • Operation auth_post_authReset

Source trace

Repository: feradelinc/feradel.auth.api
Branch: agent/auth-security-hardening
Commit: 8e09b7213fdbc5e0e1552d5271dbeee768e9dd88
Route: routes/api/v1/auth/routes.js
Handler: controller.sendChallenge
Contract: OpenAPI 3.1, source-traced and publication-validated.