Authentication — API Reference

REST API reference for the Silent Auth Call Authentication module in kasookoo-sdk-backend.

For verification options, sequence diagrams, and integration architecture, see the main Authentication Dev integration guide.

Table of contents

1. Authentication
2. Base path
3. Data model
4. Endpoints summary
5. GET /health
6. POST /sessions
7. POST /sessions/{session_id}/trigger-outbound
8. POST /sessions/{session_id}/verify
9. POST /sessions/{session_id}/verify-otp
10. GET /sessions/list
11. Verification webhook
12. Error handling
13. Related documentation

Authentication

All silent auth call endpoints require a valid SDK JWT:

Authorization: Bearer <sdk_access_token>

Mint a token via POST /api/v1/sdk/auth/client-sessions (see POSTMAN_COLLECTION_README.md).

• Tenant scope comes from the organization_id claim in the JWT (get_organization_id). Do not send organization_id in query or body — it is ignored on create.
• Session-scoped routes verify the session belongs to the JWT's organization; cross-tenant access returns 404.
• GET /sessions/list also requires SDK JWT (operator/debug listing for the authenticated tenant context).

Base path

/api/v1/silent-auth-call

All endpoints require Authorization: Bearer <sdk_access_token> unless noted.

Data model

MongoDB collection: silent_auth_call_sessions

Legacy method aliases: hybrid and outbound_missed_call are accepted for missed_outbound_call on create.

Endpoints summary

GET /health

Response (200):

{
  "configured": true,
  "did_number": "+2348012345678",
  "fixed_cli": "+2348012345678",
  "organization_id": "674a1b2c3d4e5f6789012345",
  "line_source": "primary_associated_number",
  "session_ttl_seconds": 60,
  "rate_limit": {
    "max_attempts": 5,
    "window_minutes": 10
  }
}

POST /sessions

Request body:

{
  "msisdn": "08031234567",
  "method": "callback",
  "device_fingerprint": "required-for-missed_outbound_call-or-push_otp",
  "webhook_url": "https://your-app.com/hooks/silent-auth-call-verified",
  "metadata": { "app_version": "1.2.0" }
}

organization_id in the body is ignored; org scope comes from the JWT.

Response (201):

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "method": "callback",
  "status": "pending",
  "msisdn": "+2348031234567",
  "did_number": "+2348012345678",
  "fixed_cli": null,
  "expires_at": "2026-06-12T10:01:00Z",
  "created_at": "2026-06-12T10:00:00Z",
  "verified_at": null,
  "organization_id": "674a1b2c3d4e5f6789012345"
}

POST /sessions/{session_id}/trigger-outbound

Trigger method-specific verification: SIP outbound for missed_outbound_call/voice_otp (voice OTP also sends OTP push to SDK), push notification for push_otp.

Response (200) includes outbound_triggered: true and outbound_room_name.

POST /sessions/{session_id}/verify

Used by Option 3 (Flashcall) and Option 5 (InApp).

Option 3 — Flashcall (after SDK detects missed call from fixed_cli):

{
  "device_fingerprint": "same-value-as-create",
  "timestamp": "2026-06-12T10:00:05Z"
}

Option 5 — InApp — used after the user taps Verify on the consent screen. SDK submits the code automatically from the push payload (user does not type digits).

{
  "device_fingerprint": "same-value-as-create",
  "code": "4821"
}

The code value must match the verification code shown on screen and sent in the push notification for the active push_otp session.

Response (200):

{
  "session_id": "...",
  "status": "verified",
  "verified": true,
  "msisdn": "+2348031234567",
  "verified_at": "2026-06-12T10:00:06Z"
}

POST /sessions/{session_id}/verify-otp

Option 4 — Enhanced OTP Call — used after the user taps Verify on the consent screen. SDK submits the OTP automatically from the push payload (user does not type digits).

{ "otp": "4821" }

The otp value must match the code shown on screen and sent in the push notification for the active voice_otp session.

GET /sessions/list

Debug listing. Query params: msisdn, status, limit (1–200, default 50). otp_code is excluded from results.

Verification webhook (client-provided URL)

When webhook_url is set and verification succeeds:

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "verified",
  "msisdn": "+2348031234567",
  "method": "callback",
  "verified_at": "2026-06-12T10:00:03Z"
}

Delivery is best-effort (10 s timeout).

Error handling

Related documentation

• AUTHENTICATION_DEV.md — integration guide (options, flows, architecture)
• AUTHENTICATION_DEV_MISSED_OUTBOUND_CALL.md — Flashcall option (method: missed_outbound_call, Option 3) deep dive
• AUTHENTICATION_DEV_PUSH_OTP.md — InApp option (method: push_otp, Option 5) deep dive
• POSTMAN_COLLECTION_README.md — SDK JWT and Postman setup

Kasookoo Communications Ltd · Kasookoo SDK Backend