The REST API — integrate calling, monitoring and transcripts into your own systems.

Quick start

Sixty-second path from “I have admin access” to “I’ve received my first verified webhook.” Each step links to deeper docs if you want to skip ahead.

1. Mint an API key. Sign in as admin, go to /api-keys-admin.html, click + New API key, name it, copy the ak_… value shown on creation. It is shown once. Set it in your shell so the rest of these examples work:

   export TOKEN=ak_0123456789abcdef0123456789abcdef

2. Subscribe a webhook. Go to /webhooks-admin.html, click + New webhook, paste your receiver URL (use webhook.site for a 30-second test endpoint), check the * box to receive everything, click Create. Copy the secret shown on creation — you’ll need it to verify signatures (see Webhooks → Verifying signatures below).
3. Confirm the API is alive. The unauthenticated self-describe endpoint enumerates every route. If this works, your host is reachable and the platform is configured:

   curl https://www.aloaha.com/api.ashx/v1

   Then verify your key works by listing inbound routes:

   curl -H "Authorization: Bearer $TOKEN" \
     https://www.aloaha.com/api.ashx/v1/inbound-routes

4. Place a test outbound AI call. Replace +SAFETESTNUMBER with a number you own and want to be called by an AI persona that just says “this is a test, goodbye.”

   curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "phone":        "+SAFETESTNUMBER",
       "displayName":  "Quick-start test",
       "systemPrompt": "You are testing the CodeB platform. Say: this is a test, goodbye. Then end the call.",
       "maxSeconds":   30
     }' \
     https://www.aloaha.com/api.ashx/v1/calls

   Response includes a callId like oac-0123456789ab. Watch progress at /outbound-ai-monitor.html. Step-by-step how-to with curl / Python / Node.js examples: /schedule-ai-call.html.
5. Receive + verify the webhook. Within seconds of the call ending, your receiver gets an outbound-ai.finished POST and (if the call produced one) a transcript.saved POST. The X-CodeB-Signature header is HMAC-SHA256 of the raw body with your subscription secret. Copy-paste verification code in your language is in Webhooks → Verifying signatures. Then fetch the full transcript:

   curl -H "Authorization: Bearer $TOKEN" \
     https://www.aloaha.com/api.ashx/v1/transcripts/<callId>

Authentication

Every endpoint except GET /v1 requires an OIDC access token with role=admin. Get one from the platform’s own OIDC IdP:

curl -X POST https://phone.aloaha.com/oidc.ashx/token \
  -d grant_type=password \
  -d client_id=codeb-admin \
  -d username=<your-admin-user> \
  -d password=<your-admin-password> \
  -d scope=openid

The response contains access_token — pass it on every API request:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/calls

Long-lived API keys

For server-to-server integrations that shouldn’t hold an admin password, mint an ak_-prefixed API key from the admin UI at /api-keys-admin.html. The key is shown once on creation — copy it then. It’s stored as a SHA-256 hash on disk; revoke it any time without affecting the others.

Use it as a drop-in replacement for the OIDC access token:

curl -H "Authorization: Bearer ak_a1b2c3d4e5f6…" \
  https://www.aloaha.com/api.ashx/v1/calls

Same authorisation surface, same endpoints. The only thing an ak_ key can’t do is mint another ak_ key — creating new keys still requires an admin OIDC bearer, so a leaked integration key can’t silently spawn siblings.

Primary-tenant admins are super-admins

The bridge hosts many tenants but exactly one of them is the primary tenant (configured via Bridge.PublicBaseUrl in sipbridge/appsettings.json). Any account with role=admin on the primary tenant is automatically treated as super-admin across every super-admin-gated endpoint — no separate superuser=true claim required.

This matches operator expectation: the team running the primary deployment owns the box and shouldn’t have to maintain a parallel superuser account just to call cross-tenant endpoints. Admins of secondary tenants stay scoped to their own tenant’s data exactly as before.

Conventions

• Pagination. Collection endpoints accept ?limit=N&offset=M (defaults 50 / 0; limit capped at 500). Response shape: { data, total, limit, offset, next } where next is the relative URL to the next page (null on the last page).
• Field casing. All response item fields use camelCase (e.g. did, fromNumber, createdAtUtc). Request bodies accept either case — did or Did — for compatibility with earlier examples, but emit camelCase going forward.
• Build version. The /v1 root response carries a build field (e.g. "2026-06-09-list-envelope") so integrators can detect handler updates from monitoring.
• Errors. { error, error_description }. HTTP status: 400 bad input, 401 missing/invalid bearer, 403 bearer lacks role=admin, 404 resource not found, 405 method not allowed, 502 bridge unreachable, 503 bridge not configured.
• Caching. Every response is Cache-Control: no-store. Don’t cache API replies in your client.
• Webhooks. Real-time events (call.ended, transcript.saved, outbound-ai.finished) are delivered via the platform’s webhook system. REST for pull, webhooks for push.

Outbound AI calls

Request body (JSON):

Example:

curl -X POST https://www.aloaha.com/api.ashx/v1/calls \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone":        "+15551234567",
    "displayName":  "Reminder",
    "email":        "ops@example.com",
    "systemPrompt": "You are calling Alex to remind them about a test appointment tomorrow at 14:00.",
    "apiKey":       "AIza...",
    "voice":        "Aoede",
    "language":     "en-US",
    "maxSeconds":   180
  }'

Response (200):

{
  "ok": true,
  "callId": "oac-0123456789ab",
  "tenant": "www.aloaha.com",
  "whitelistAdded": true,
  "whitelistError": null,
  "bridgeReply": "{...}"
}

Query params:

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aloaha.com/api.ashx/v1/calls?status=in-flight,scheduled&limit=20"

Response (200):

{
  "data": [
    {
      "callId":           "oac-0123456789ab",
      "tenant":           "www.aloaha.com",
      "requestedBy":      "alex",
      "phone":            "+15551234567",
      "displayName":      "Reminder",
      "email":            "ops@example.com",
      "voice":            "Aoede",
      "language":         "en-US",
      "model":            "models/",
      "status":           "in-flight",
      "createdAtUtc":     "2026-06-04T17:55:12.401Z",
      "scheduledForUtc":  null,
      "dispatchedAtUtc":  "2026-01-01T12:00:00.000Z",
      "answeredAtUtc":    "2026-01-01T12:00:05.500Z",
      "endedAtUtc":       null,
      "endedReason":      "",
      "durationSec":      0,
      "trunkId":          "tr_0123456789abcdef",
      "transcriptPath":   "",
      "errorDetail":      "",
      "attempt":          1,
      "retriesLeft":      2,
      "retryDelayMinutes": 5
    }
  ],
  "total":  1,
  "limit":  20,
  "offset": 0,
  "next":   null
}

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/calls/oac-0123456789ab

Response (200):

{
  "callId":          "oac-0123456789ab",
  "tenant":          "www.aloaha.com",
  "requestedBy":     "alex",
  "phone":           "+15551234567",
  "displayName":     "Reminder",
  "status":          "ended-success",
  "createdAtUtc":    "2026-06-04T17:55:12.401Z",
  "dispatchedAtUtc": "2026-01-01T12:00:00.000Z",
  "answeredAtUtc":   "2026-01-01T12:00:05.500Z",
  "endedAtUtc":      "2026-01-01T12:02:30.000Z",
  "endedReason":     "finished",
  "durationSec":     145,
  "trunkId":         "tr_0123456789abcdef",
  "transcriptPath":  "outbound-ai-20260101-120000-oac-0123456789ab.txt",
  "attempt":         1,
  "retriesLeft":     0
}

Response (404) — no such call:

{ "error": "not_found", "error_description": "No call with id=oac-..." }

No body required — the callId comes from the path.

Example:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/calls/oac-0123456789ab/hangup

Response (200):

{
  "ok":         true,
  "callId":    "oac-0123456789ab",
  "newStatus": "cancelled",
  "actor":     "alex"
}

Virtual numbers

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/numbers

Response (200):

{
  "data": [
    {
      "name":         "codebdemo",
      "number":       "1234",
      "mode":         "live-voice-ai",
      "voice":        "Aoede",
      "language":     "en-US",
      "saveTranscripts": true,
      "maxDurationSec": 3500,
      "visibility":   "public"
    },
    {
      "name":         "MUSC",
      "number":       "24345",
      "mode":         "live-voice-ai",
      "voice":        "Charon",
      "language":     "en-US",
      "saveTranscripts": true,
      "maxDurationSec": 3500,
      "visibility":   "signed-in"
    }
  ],
  "total":  15,
  "limit":  50,
  "offset": 0,
  "next":   null,
  "tenant": "www.aloaha.com"
}

Top-level fields follow the standard list envelope. tenant is included as a sibling for transparency (matches the bearer's tenant claim). Each item is a virtual-number record; sensitive fields like geminiApiKey and systemPrompt are present in the live response but never logged.

Transcripts

Query params:

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aloaha.com/api.ashx/v1/transcripts?source=outbound-ai&limit=10"

Response (200):

{
  "data": [
    {
      "callId":       "oac-0123456789ab",
      "callerSource": "outbound-ai",
      "startedUtc":   "2026-01-01T12:00:00.000Z",
      "endedUtc":     "2026-01-01T12:02:30.000Z",
      "mtimeUtc":     "2026-06-04T17:57:44.649Z",
      "durationSec":  150,
      "rule":         "outbound: +15551234567 (Reminder)",
      "phone":        "+15551234567",
      "displayName":  "Reminder",
      "outcome":      "finished",
      "voice":        "Aoede",
      "language":     "en-US",
      "model":        "live-voice-ai",
      "tokensTotal":  18420,
      "tokensPrompt": 1240,
      "turnCount":    12,
      "size":         8412,
      "source":       "tenant",
      "file":         "outbound-ai-20260101-120000-oac-0123456789ab.txt"
    },
    {
      "callId":       "vnum0123456789ab",
      "callerSource": "office-tab",
      "startedUtc":   "2026-06-04T17:14:03.836Z",
      "endedUtc":     "2026-06-04T17:15:19.500Z",
      "durationSec":  75,
      "rule":         "vnum:Shortletsmalta",
      "number":       "666",
      "outcome":      "empty-room",
      "tokensTotal":  6240,
      "turnCount":    8,
      "size":         3104,
      "file":         "vnum-1234-20260101-120000-vnum0123456789ab.txt"
    }
  ],
  "total":  47,
  "limit":  10,
  "offset": 0,
  "next":   10
}

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/transcripts/oac-0123456789ab

Response (200):

{
  "callId":        "oac-0123456789ab",
  "callerSource":  "outbound-ai",
  "tenant":        "www.aloaha.com",
  "requestedBy":   "alex",
  "phone":         "+15551234567",
  "displayName":  "Reminder",
  "email":         "ops@example.com",
  "voice":         "Aoede",
  "language":      "en-US",
  "model":         "models/",
  "trunkId":       "tr_0123456789abcdef",
  "startedUtc":    "2026-01-01T12:00:00.000Z",
  "answeredUtc":   "2026-01-01T12:00:05.500Z",
  "endedUtc":      "2026-01-01T12:02:30.000Z",
  "durationSec":   150,
  "answered":      true,
  "outcome":       "finished",
  "errorDetail":   "",
  "inputTurns":    6,
  "outputTurns":   6,
  "tokensTotal":   18420,
  "turns": [
    { "speaker": "AI",     "text": "Hi Alex, calling about your test appointment tomorrow at 14:00.", "ts": "2026-01-01T12:00:06.450Z" },
    { "speaker": "Caller", "text": "Hi, yes, what about it?",                                              "ts": "2026-01-01T12:00:10.880Z" },
    { "speaker": "AI",     "text": "Just confirming you'll be there. Do you need to reschedule?",          "ts": "2026-01-01T12:00:15.120Z" }
  ]
}

Response (404) — no transcript for that callId:

{ "error": "not_found", "error_description": "No transcript for callId=oac-..." }

Inbound routes

Read the per-tenant inbound DID routing table. The bridge uses first-match semantics by Did — the first row whose Did matches the incoming INVITE wins. "*" is the catchall row (always present; auto-inserted if missing).

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/inbound-routes

Response (200):

{
  "data": [
    { "did": "+15551234567",                       "user": "alex" },
    { "did": "anonymous",      "fromNumber": "*",   "user": "callcentre" },
    { "did": "*",                                    "user": "codeb" }
  ],
  "total":  3,
  "limit":  50,
  "offset": 0,
  "next":   null
}

Each row has did (required, the matched value), an optional fromNumber filter, and user (the office-tab user the call rings). did can be a phone number, an extension, "anonymous" (calls with no caller ID), or "*" (catchall — runs if no earlier row matched).

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/inbound-routes/%2A

Response (200):

{ "did": "*", "user": "codeb" }

Response (404) — no row with that did:

{ "error": "not_found", "error_description": "No inbound route with did='+4400000000'" }

Request body:

{
  "Did":         "+15551234567",       // required: phone, extension, "anonymous", or any matchable string
  "FromNumber":  "+356*",                // optional: restrict to calls FROM this pattern
  "User":        "alex"                // required: office-tab user that should ring
}

Example:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Did":"+15551234567","User":"alex"}' \
  https://www.aloaha.com/api.ashx/v1/inbound-routes

Response (201): the created row, echoed back.

{ "Did": "+15551234567", "User": "alex" }

Response (409) — a route with the same Did + FromNumber pair already exists:

{ "error": "duplicate_route", "error_description": "An inbound route already exists for Did='+15551234567'" }

Query string:

• fromNumber — optional. Omit to address the row with no FromNumber filter; provide to address a row scoped to a specific caller pattern.

Request body:

{ "User": "newuser" }

Example — rotate the catchall to a new user:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"User":"frontdesk"}' \
  https://www.aloaha.com/api.ashx/v1/inbound-routes/%2A

Example — update a FromNumber-scoped route:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"User":"callcentre"}' \
  'https://www.aloaha.com/api.ashx/v1/inbound-routes/anonymous?fromNumber=%2A'

Response (200): the updated row.

{ "Did": "anonymous", "FromNumber": "*", "User": "callcentre" }

Response (404) — no row matches the (Did, FromNumber) composite:

{
  "error": "not_found",
  "error_description": "No inbound route with Did='anonymous' FromNumber='*'"
}

Example:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/inbound-routes/%2B15551234567

Response (200):

{ "deleted": { "Did": "+15551234567", "User": "alex" } }

Response (400) — tried to delete the catchall:

{
  "error": "cannot_delete_catchall",
  "error_description": "The '*' catchall row cannot be deleted -- the bridge requires it for unmatched inbound calls"
}

Response (404) — no matching row:

{ "error": "not_found", "error_description": "No inbound route with Did='+4400000000'" }

Outbound routes

Read and manage the per-tenant outbound dial routing table. The bridge picks the first row whose match pattern fits the dialled number and dials through one of the listed trunkIds. The catch-all is the defaultTrunkId that lives at the top level of the response.

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/outbound-routes

Response (200):

{
  "data": [
    { "match": "+356*",  "trunkIds": [ "malta" ] },
    { "match": "+49*",   "trunkIds": [ "upstairs-de", "downstairs-de" ] },
    { "match": "global", "trunkIds": [ "malta" ] }
  ],
  "defaultTrunkId": "malta",
  "total":  3,
  "limit":  50,
  "offset": 0,
  "next":   null
}

Each row has match (the dial-prefix pattern; * = wildcard suffix; the literal string "global" is the catch-all matcher) and trunkIds (an ordered list — the bridge tries them in order until one accepts the INVITE).

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/outbound-routes/%2B356%2A

Response (200):

{ "match": "+356*", "trunkIds": [ "malta" ] }

Response (404) — no row with that match:

{ "error": "not_found", "error_description": "No outbound route with match='+44*'" }

Request body:

{
  "match":    "+44*",                    // required: dial-prefix pattern
  "trunkIds": [ "uk-primary", "uk-failover" ]  // required: ordered trunk list
}

Example:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"match":"+44*","trunkIds":["uk-primary"]}' \
  https://www.aloaha.com/api.ashx/v1/outbound-routes

Response (201):

{ "match": "+44*", "trunkIds": [ "uk-primary" ] }

Response (409) — a route with that match already exists.

Request body:

{ "trunkIds": [ "uk-primary", "uk-failover" ] }

Example:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trunkIds":["uk-primary","uk-failover"]}' \
  https://www.aloaha.com/api.ashx/v1/outbound-routes/%2B44%2A

Response (200): the updated row.

{ "match": "+44*", "trunkIds": [ "uk-primary", "uk-failover" ] }

Example:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/outbound-routes/%2B44%2A

Response (200):

{ "deleted": { "match": "+44*", "trunkIds": [ "uk-primary" ] } }

Response (404) — no matching row.

Webhooks

Read the per-tenant webhook subscription list. Subscriptions are created and managed through the admin UI at /webhooks-admin.html — this endpoint exists so integrators can verify their subscriptions are active and discover which events the platform is firing.

Example:

curl -H "Authorization: Bearer $TOKEN" \
  https://www.aloaha.com/api.ashx/v1/webhooks

Response (200):

{
  "data": [
    {
      "id":           "0123456789abcdef",
      "url":          "https://hooks.example.com/codeb",
      "events":       [ "*" ],
      "active":       true,
      "createdAtUtc": "2026-01-01T12:00:00.000Z",
      "createdBy":    "alex",
      "lastFiredUtc": "2026-01-01T12:00:05.000Z",
      "failures":     0
    },
    {
      "id":           "fedcba9876543210",
      "url":          "https://ops.example.com/codeb-alerts",
      "events":       [ "call.ended", "transcript.saved" ],
      "active":       false,
      "createdAtUtc": "2026-01-01T08:00:00.000Z",
      "createdBy":    "alex",
      "lastFiredUtc": null,
      "failures":     20
    }
  ],
  "total":  2,
  "limit":  50,
  "offset": 0,
  "next":   null
}

Each item: id (16-hex), url (the operator’s receiver endpoint), events (array of event names or ["*"] for all), active (auto-paused after 20 consecutive delivery failures), and counters for the last successful fire + the consecutive-failure tally. The bridge fires events automatically as calls happen; see /webhooks-admin.html to subscribe.

Event catalogue

The bridge fires three events today. Subscribe to "*" to receive all of them, or list specific names. All deliveries POST JSON to the subscriber’s URL with a top-level envelope:

{
  "event":  "<name>",
  "tenant": "www.aloaha.com",
  "ts":     "2026-01-01T12:00:00.000Z",
  "data":   { /* event-specific fields */ }
}

Headers on every POST:

• X-CodeB-Event — the event name (e.g. call.ended)
• X-CodeB-Signature — sha256=<hex> HMAC-SHA256 of the raw body using your subscription’s secret
• X-CodeB-Delivery-Id — stable across retries (use it to de-dup on your side)
• X-CodeB-Attempt — 1 through 4. Retries follow 5 s → 30 s → 120 s back-off; after 20 consecutive failures the subscription auto-pauses.

Verifying signatures

On every delivery, compute HMAC-SHA256 of the raw request body using your subscription’s secret, hex-encode it, prefix with sha256=, and compare in constant time against X-CodeB-Signature. Reject mismatches with HTTP 401 — the bridge will retry with the same signature, so a real delivery eventually succeeds while a spoofed one keeps failing.

Python (Flask):

import hmac, hashlib
from flask import Flask, request, abort

SECRET = b"your_subscription_secret"  # from /webhooks-admin.html on create

app = Flask(__name__)

@app.post("/codeb-webhook")
def codeb_webhook():
    body = request.get_data()  # raw bytes -- DO NOT use request.json here
    got  = request.headers.get("X-CodeB-Signature", "")
    want = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(got, want):
        abort(401)
    event = request.headers.get("X-CodeB-Event", "")
    delivery = request.headers.get("X-CodeB-Delivery-Id", "")
    # ... process event ...
    return "", 200

Node.js (Express):

const express = require("express");
const crypto  = require("crypto");

const SECRET = "your_subscription_secret";
const app = express();

// IMPORTANT: capture the raw body BEFORE express.json() parses it.
app.post("/codeb-webhook", express.raw({ type: "*/*" }), (req, res) => {
  const got  = req.headers["x-codeb-signature"] || "";
  const want = "sha256=" +
    crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

  const gotBuf  = Buffer.from(got);
  const wantBuf = Buffer.from(want);
  if (gotBuf.length !== wantBuf.length ||
      !crypto.timingSafeEqual(gotBuf, wantBuf)) {
    return res.status(401).end();
  }

  const event = req.headers["x-codeb-event"];
  const payload = JSON.parse(req.body.toString("utf8"));
  // ... process event ...
  res.status(200).end();
});

Bash (debugging):

SECRET="your_subscription_secret"
BODY=$(cat)                              # raw stdin
EXPECTED="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')"
echo "$EXPECTED"
# compare against the X-CodeB-Signature header you received

Payload (data):

{
  "callId":     "vnum0123456789ab",
  "number":     "1234",                  // vnum / SIP inbound only
  "did":        "+15551234567",        // SIP inbound only
  "phone":      "+15551234567",        // outbound-ai only
  "displayName":"Reminder",              // outbound-ai only
  "room":       "vnum-1234-d0va4s42",    // vnum only
  "direction":  "inbound",               // "inbound" | "outbound"
  "source":     "vnum"                   // "vnum" | "gemini-live" | "outbound-ai"
}

Payload (data):

{
  "callId":      "oac-0123456789ab",
  "phone":       "+15551234567",        // outbound-ai only
  "displayName": "Reminder",              // outbound-ai only
  "did":         "+15551234567",        // SIP inbound only
  "fromNumber":  "+15551234567",        // SIP inbound only
  "trunkId":     "tr_0123456789abcdef",   // outbound-ai only
  "direction":   "outbound",              // "outbound" | "inbound"
  "source":      "outbound-ai",           // "outbound-ai" | "gemini-live"
  "answerMs":    2755                      // ms from INVITE/Ring to 200 OK
}

Payload (data):

{
  "callId":       "vnum0123456789ab",
  "fromVnum":     "8888",                  // vnum source only
  "fromOutbound": "oac-0123456789ab",      // outbound-ai source only
  "fromPhone":    "+15551234567",        // outbound-ai source only
  "toUser":       "alex",                // SIP / extension target
  "toPhone":      "+15551234567",        // PSTN target (vnum-to-pstn only)
  "transferType": "vnum-to-pstn",          // "vnum-to-vnum"|"vnum-to-officetab"|"vnum-to-pstn"|"outbound-to-user"
  "trunkId":      "tr_0123456789abcdef",   // outbound-to-user only
  "room":         "vnum-8888-d0va4s42",    // vnum source only
  "source":       "vnum"                   // "vnum" | "outbound-ai"
}

Payload (data):

{
  "callId":      "vnum0123456789ab",
  "number":      "1234",                 // vnum number, or DID for inbound SIP
  "room":        "vnum-1234-d0va4s42",   // signaling room name
  "outcome":     "empty-room",           // see outcome glossary below
  "durationSec": 39,
  "tokens":      24823,                  // AI Voice Engine tokens used (input+output)
  "source":      "vnum"                  // "vnum" | "sip"
}

Payload (data):

{
  "callId":      "oac-0123456789ab",
  "phone":       "+15551234567",
  "displayName": "Reminder",
  "outcome":     "finished",             // see outcome glossary below
  "answered":    true,
  "talkSec":     150,
  "trunk":       "tr_0123456789abcdef",
  "inputTurns":  6,                       // caller turns recorded by the AI Voice Engine
  "outputTurns": 6,                       // AI turns
  "errorDetail": ""                       // populated on technical failures
}

Payload (data):

{
  "callId":      "oac-0123456789ab",
  "phone":       "+15551234567",        // outbound-ai only; absent for vnum
  "displayName": "Reminder",              // outbound-ai only; absent for vnum
  "number":      "1234",                  // vnum only; absent for outbound-ai
  "file":        "outbound-ai-20260101-120000-oac-0123456789ab.txt",
  "outcome":     "finished",
  "source":      "outbound-ai"            // "outbound-ai" | "vnum"
}

Fetch the full transcript JSON via GET /v1/transcripts/{callId} after receiving this event.

Payload (data):

{
  "token":     "...abc12345",                // last 8 chars only -- safe to log
  "file":      "vnum-office-1234-20260101T120000Z-vnum0123456789ab.txt",
  "ttlHours":  168,                          // 0 = never expires
  "createdBy": "alex",                     // OIDC preferred_username / sub
  "expiresUtc": "2026-01-08T12:00:00.000Z"   // null if ttlHours == 0
}

Payload (data):

{
  "token":    "...abc12345",
  "file":     "vnum-office-1234-...",
  "viewerIp": "203.0.113.42"
}

Payload (data):

{
  "token":     "...abc12345",
  "file":      "vnum-office-1234-...",
  "revokedBy": "alex"
}

Room cascade events

Fires when a meeting room flips media topology between peer-to-peer mesh and server-side fan-out (SFU). Two triggers: auto (a 7th human joiner crosses the mesh capacity threshold) and admin (operator flips mode via /sfu.html or the ?sfu-mode= REST endpoint). See dataflow.html for the topology background.

Payload (data):

{
  "room":          "vnum-1234-d0va4s42",
  "mode":          "sfu",
  "reason":        "auto-promote-join-human-count-7",     // or "auto-promote-bandwidth-degraded-stressed-N-of-M", "admin-override"
  "trigger":       "auto-join",                            // "auto-join" | "auto-bandwidth" | "admin"
  "humanCount":    7,                                      // auto-join + auto-bandwidth (count at trigger time)
  "stressedCount": 3,                                      // auto-bandwidth only -- peers above threshold
  "peerCount":     5,                                      // auto-bandwidth only -- total peers (incl. ai-vnum / sip-bridge)
  "actor":         "alex"                                  // admin only -- OIDC preferred_username / sub
}

Payload (data):

{
  "room":    "vnum-1234-d0va4s42",
  "mode":    "mesh",
  "reason":  "admin-override",                       // or operator-supplied reason
  "trigger": "admin",
  "actor":   "alex"                                // OIDC preferred_username / sub
}

Payload (data):

{
  "room":       "vnum-1234-d0va4s42",
  "mode":       "sfu",                               // or "mesh" -- direction that FAILED
  "reason":     "auto-promote-join-human-count-7",  // or "admin-override"
  "trigger":    "auto-join",                         // "auto-join" | "admin"
  "humanCount": 7,                                   // auto-join only
  "actor":      "alex",                            // admin only
  "error":      "BridgeUnreachable: connection refused"   // truncated to 200 chars
}

Room presence events

Fires every time a peer joins or leaves a meeting room. Use these to mirror live presence into a CRM, drive a wall-board, run billing per-minute counters, or push notifications to other channels when a specific person walks in. Both events tenant-scoped via webhook subscription.

Payload (data):

{
  "room":      "vnum-1234-d0va4s42",
  "peerId":    "f3d5452776f5",
  "name":      "alex",                       // peer-supplied display name
  "role":      "human",                      // "human" | "ai-vnum" | "sip-bridge"
  "verified":  false,                        // true if X-CodeB-Identity / OIDC backed
  "ip":        "203.0.113.42",
  "joinPath":  "direct",                     // "direct" | "admit"
  "peerCount": 3                             // total peers in the room AFTER this join
}

Payload (data):

{
  "room":      "vnum-1234-d0va4s42",
  "peerId":    "f3d5452776f5",
  "name":      "alex",
  "role":      "human",
  "verified":  false,                        // mirrored from the peer.joined event
  "ip":        "203.0.113.42",
  "reason":    "ws-close",                   // future values: "kick", "timeout"
  "peerCount": 2                             // total peers in the room AFTER this leave (0 if room emptied)
}

peerCount vs humanCount. Presence events count every peer in the room — browser humans, server-side AI personas (ai-vnum), and SIP-bridge legs (sip-bridge). The cascade events’ humanCount is narrower: browser-humans only (used to decide when to flip mesh → SFU). Use peerCount for billing / CDR / capacity; use cascade events’ humanCount for topology decisions.

Room health events

Fires when multiple peers in a room report sustained network stress at the same time. Use it to alert ops, prompt an admin to flip the room to SFU, surface a degraded-call warning to the host, or trigger a customer-side capacity check. Browser peers report bandwidth, packet loss, and RTT to signal.ashx every few seconds; this event is the room-wide rollup, not per-peer noise.

Payload (data):

{
  "room":           "vnum-1234-d0va4s42",
  "stressedCount":  3,                      // peers currently above threshold within the rolling window
  "peerCount":      5,                      // total peers in the room (incl. ai-vnum / sip-bridge legs)
  "humanCount":     5,                      // browser-humans only (for cascade-trigger correlation)
  "windowSec":      30,                     // rolling window the count covers
  "triggerPeerId":  "f3d5452776f5",         // the peer whose report tipped the eval over the line
  "sampleMetrics": {
    "abrMbps":      0.92,                   // minimum outgoing bitrate observed at trigger time (Mbps)
    "lossPct":      7.4,                    // peak packet-loss percentage
    "rttMs":        420                     // peak RTT in milliseconds
  }
}

Per-tenant SFU tunables

Every SFU threshold is configurable per tenant via your appsettings.json under the WebPhone:Sfu:* namespace. Defaults below are the safe values shipped out of the box; clamping ranges are enforced server-side (out-of-range values silently snap to the nearest valid boundary).

All eight keys are hot-reloaded — edit appsettings.json and the next eval picks up the new value (no IIS restart needed). The bw-degraded-fire connection-log line emits the effective values alongside each fire, so you can verify the in-effect config from logs.

SFU signaling events

Fires when a browser interacts with the SFU. (this build) ships end-to-end audio fan-out — peer A's published RTP arrives at the bridge and is forwarded to every peer B that has subscribed to A. Each (publisher, subscriber) edge has its own RTCPeerConnection with fresh DTLS-SRTP keys; the bridge does NOT mix on the browser-facing leg (the receiving browser composites multiple inbound streams locally). Subscriber-side conference.js wiring is the next round; today these events are operator-testable via wscat.

Payload (data):

{
  "room":       "vnum-1234-d0va4s42",
  "peerId":     "f3d5452776f5",
  "role":       "human",
  "offerLen":   2840,                              // bytes of SDP the browser sent
  "outcome":    "failed",                          // "answer" (1b.1+) | "failed"
  "code":       "not-implemented",                 // bridge-supplied error code on failure
  "phase":      "1b.1-live",                       // bridge-supplied phase marker (or "1b.1-live" w/ ok=true)
  "httpStatus": 200                                // bridge HTTP status code (200 on success; 4xx/5xx on failure)
}

Payload (data):

{
  "room":          "vnum-1234-d0va4s42",
  "peerId":        "f3d5452776f5",
  "role":          "human",
  "connectedUtc":  "2026-06-15T14:23:18.456Z",   // when the SFU connection became healthy
  "packetsAtConn": 0                              // RTP packets received at moment of fire
}

Payload (data):

{
  "room":             "vnum-1234-d0va4s42",
  "publisherPeerId":  "f3d5452776f5",            // upstream publisher
  "subscriberPeerId": "a8e21fc09d12",            // receiving browser
  "offerLen":         2840,                       // bytes of SDP the browser sent
  "outcome":          "answer",                   // "answer" | "failed"
  "code":             null,                       // bridge-supplied error code on failure
  "phase":            "1b.2-live",
  "httpStatus":       200
}

Payload (data):

{
  "room":                  "vnum-1234-d0va4s42",
  "publisherPeerId":       "f3d5452776f5",
  "subscriberPeerId":      "a8e21fc09d12",
  "connectedUtc":          "2026-06-15T14:23:18.789Z",
  "packetsForwardedAtConn": 0                       // typically 0; first forwarded packet usually arrives in the same ms
}

Payload (data):

{
  "room":     "vnum-1234-d0va4s42",
  "peerId":   "f3d5452776f5",
  "role":     "human",
  "prevPref": "auto",
  "newPref":  "prefer-sfu",
  "voteTally": { "auto": 3, "prefer-mesh": 1, "prefer-sfu": 2 },
  "effectiveThreshold": 5
}

Need a different event?

The list above is what fires today. We add events when integrators ask for them — SIP-register, trunk health, license-threshold crossings, custom CDR shapes, EU Wallet verifier outcomes … tell us what you need and we’ll wire it up against your existing webhook subscription.

Outcome glossary

The outcome field is a short string that captures how the call ended. Use it to route follow-up actions.

Bridge security: TURN ACL gate & TLS auto-blacklist

The TURN server applies two complementary defences against unwanted inbound traffic, both managed without a deploy. They run on every TURN accept path — UDP/3478, TCP/3478, TLS/5349 and TLS/443.

ACL gate — operator-curated allow / deny

The same acl.html admin page that gates SIP traffic now also gates TURN media. When the operator adds a blacklist entry for an IP or CIDR (e.g. 62.210.136.0/22), all four TURN accept paths drop traffic from that source at the socket level — no SslStream allocation, no STUN parse, no per-IP quota cost.

• Rule subjects honoured: ip and cidr. Identity-shaped subjects (sip-user, sip-from, sip-did, tenant, user-agent) are skipped — TURN packets carry no such fields.
• Scopes honoured: sip-inbound, pstn-outbound, or any. An IP-shaped rule under any of these scopes applies to TURN too. A rule scoped to any with subject-type cidr is the cleanest way to block a scanner range from both SIP and TURN with one entry.
• Per-tenant rules are not consulted. TURN is single-process across all tenants; only the global rule pool applies. Per-tenant ACL still works for SIP as before.
• Private / loopback / link-local IPs always allowed. Same exemption as the SIP gate — a misconfigured blanket-deny cannot lock the operator off the LAN.
• No mode-default for TURN. An operator who flips ModeSipInbound to deny for SIP will not accidentally lock all browsers out of their own TURN. No-match always allows.
• Per-IP log throttle. The gate emits one INF line per blocked source IP per minute, with the matched rule id and reason. The counter increments unthrottled so the stats line shows the true block volume.

TLS auto-blacklist — self-driving scanner defence

Per-source-IP sliding-window detector: more than 5 failed TLS handshakes from one IP in a 5-minute window blocks that IP at the TLS accept layer for 1 hour. Catches the noisy Censys / Palo Alto Xpanse-class scanners that hit TURN/5349 looking for misconfigured allocations.

• Three handshake-fail paths feed the detector: no-cert-loaded, handshake timeout (Slowloris-style stall), and any other handshake exception (junk ClientHello).
• Blocked IPs are auto-expired after 1 hour. A legitimate user who fumbles a renewal is not locked out forever.
• Private / loopback / link-local IPs never auto-blocked, regardless of failure count — same self-lockout protection as the manual ACL.
• First-block is race-safe. Concurrent failing handshakes from the same IP produce exactly one "blocked" INF line via TryAdd; the win race is decided atomically.
• Memory-bounded: a ReaperLoop janitor prunes per-IP failure history and log-throttle dictionaries that haven't seen recent activity. A scanner that fires once and disappears does not leak forever.

Observability

The periodic TURN stats line (every 30 s) now includes both subsystems:

TURN stats: active=... 
  acl(blocked=N) 
  tls(accepted=A hsFail=H certReloads=R autoBlk=Z blockedIps=B) 
  ...

• acl(blocked=N) — total connections dropped by an operator ACL rule this lifetime.
• tls(autoBlk=Z blockedIps=B) — total connections refused by the auto-blacklist this lifetime; current size of the live block list.

Order of precedence (when both fire)

1. Operator ACL blacklist runs first — a manual block always wins over the self-driving detector. Both INF logs are emitted; the ACL counter increments.
2. TLS auto-blacklist runs second on TLS-only paths if the ACL didn't already block.
3. Per-IP allocation quota and unauth-binding rate-limits run third.

Both subsystems are operator-controlled at /acl.html (admin / superuser only). No REST endpoints are exposed publicly — the bridge applies rules on the wire and surfaces blocks in the stats line and per-IP INF logs.

Outbound number whitelist (per-tenant)

Outbound PSTN dials pass through a FraudGuard whitelist check before the bridge places the INVITE. The whitelist lives in App_Data/<tenant>/appsettings.json under WebPhone:NumberWhitelist (string array) and WebPhone:WhitelistComments (object mapping number to operator-supplied label). Both keys hot-reload on file change — no bridge restart needed after a save.

List the whitelist

HMAC canonical: whitelist-list|<tenant>

Response (200):

{
  "tenant": "phone.aloaha.com",
  "numbers": [
    { "number": "+15551234567", "comment": "sample number" },
    { "number": "+15551234568", "comment": "sample number" }
  ],
  "count": 2
}

Add a single number

HMAC canonical: whitelist-add|<tenant>|<bodyLen>

Request body (JSON):

Example:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"number":"+15551234569","comment":"Acme Ltd. main switchboard"}' \
  https://phone.aloaha.com/signal.ashx?whitelist=add

Response (200) — new number:

{
  "ok": true,
  "tenant": "phone.aloaha.com",
  "number": "+15551234569",
  "comment": "Acme Ltd. main switchboard",
  "added": true,
  "count": 3
}

Response (200) — number already present (idempotent):

{
  "ok": true,
  "tenant": "phone.aloaha.com",
  "number": "+15551234569",
  "comment": "Acme Ltd. main switchboard (updated)",
  "added": false,
  "count": 3
}

Replace the entire whitelist

HMAC canonical: whitelist-write|<tenant>|<bodyLen>

Request body (JSON):

{
  "numbers": [
    { "number": "+15551234567", "comment": "sample number" },
    { "number": "+15551234568", "comment": "sample number" }
  ]
}

Response (200):

{ "ok": true, "tenant": "phone.aloaha.com", "count": 2 }

Error responses

• 400 — { "error": "body must be { number, comment? }" } or { "error": "number empty or too long (max 32)" }
• 401 — { "error": "bad signature" } — missing or wrong bearer / HMAC.
• 405 — method must be POST.
• 500 — { "error": "read failed: …" } or { "error": "write NumberWhitelist failed: …" } — underlying file IO error; the change was NOT applied.
• 503 — { "error": "admin disabled: set WebPhone:AdminSharedSecret (>=24 chars)" } or { "error": "App_Data/appsettings.json not found for this tenant" } — admin gate not configured yet.

OIDC client management (per-tenant)

Each tenant operates its own embedded OIDC IdP at /oidc.ashx (issuer = https://<tenant-host>). Third-party applications register as OAuth 2.0 / OIDC clients with a client_id and (optionally) a client_secret. Use these admin endpoints to list, create, update, regenerate secrets for, and delete the tenant’s OIDC clients.

List clients

Response (200):

{
  "count": 2,
  "tenant": "phone.aloaha.com",
  "issuer": "https://phone.aloaha.com",
  "discovery_url": "https://phone.aloaha.com/.well-known/openid-configuration",
  "items": [
    {
      "client_id": "codeb-admin",
      "redirect_uris": ["https://phone.aloaha.com/oidc-callback.html"],
      "post_logout_redirect_uris": [],
      "description": "Built-in CodeB admin UI (read-only, hard-coded in oidc.ashx)",
      "client_type": "public",
      "has_secret": false,
      "builtin": true
    },
    {
      "client_id": "example-saas-app",
      "redirect_uris": ["https://app.example.com/auth/oidc/callback"],
      "post_logout_redirect_uris": ["https://app.example.com/logout"],
      "description": "Example SaaS app federating sign-in via this tenant",
      "client_type": "confidential",
      "has_secret": true,
      "builtin": false
    }
  ]
}

Save / create / update a client

Request body (JSON):

Response (200):

{ "ok": true, "client_id": "example-saas-app", "has_secret": true }

Generate a fresh client secret

Request body (JSON):

{ "client_id": "example-saas-app" }

Response (200) — the only time the secret is returned in cleartext:

{
  "ok": true,
  "client_id": "example-saas-app",
  "client_secret": "<48-char URL-safe random>"
}

Delete a client

Response (200):

{ "ok": true, "client_id": "example-saas-app", "deleted": true }

Integration recipe (third-party app)

1. Pick a client_id (lowercase, hyphen-separated, unique within the tenant).
2. POST to /signal.ashx?oidc-clients-save=1 with client_id, redirect_uris, and description.
3. POST to /signal.ashx?oidc-clients-genkey=1 to mint and capture the secret.
4. In the integrating application, set the IdP discovery URL to https://<tenant-host>/.well-known/openid-configuration and configure the client_id + client_secret.
5. Drive the standard authorization-code + PKCE flow against https://<tenant-host>/oidc.ashx/authorize and exchange the code at /oidc.ashx/token.

Local chat — 1:1 messaging + real-time push

CodeB ships a first-class local chat channel that lives alongside the voice stack. Two authenticated users on the same tenant can direct-message each other; messages persist to per-tenant JSON files (no external database) and can be delivered in real time over WebSocket. This is the same backend the browser /chat.html UI drives — use these APIs to embed chat in your own portal, CRM, or ticketing system, or to bridge messages into an existing helpdesk.

Who am I

Response (200):

{ "tenant": "phone.aloaha.com", "login": "alice", "displayName": "Alice Example" }

List tenant users (peer picker)

Response (200):

{
  "tenant": "phone.aloaha.com", "self": "alice",
  "users": [
    { "login": "bob", "displayName": "Bob Example", "email": "bob@example.com", "role": "user" }
  ]
}

List my DM threads

Response (200):

{
  "self": "alice", "hasMore": false, "pageCap": 200,
  "threads": [
    {
      "pairKey": "dm-alice_bob",
      "peerLogin": "bob",
      "peerName": "Bob Example",
      "lastMessageUtc": "2026-07-02T14:23:11.4123456Z",
      "lastMessagePreview": "See you at 3.",
      "unread": 2
    }
  ]
}

Fetch messages in a thread

Response (200):

{
  "self": "alice", "peerLogin": "bob", "peerName": "Bob Example",
  "pairKey": "dm-alice_bob",
  "messages": [
    {
      "id": "1782968591234-9x8b3q",
      "tsUtcMs": 1782968591234,
      "tsUtcIso": "2026-07-02T14:23:11.234Z",
      "senderLogin": "bob",
      "senderDisplayName": "Bob Example",
      "recipientLogin": "alice",
      "body": "See you at 3."
    }
  ]
}

Send a message

Rate limit: per-user token bucket — burst 30 messages, sustained ~30/min. Over the cap returns HTTP 429 with Retry-After: 2 and a problem+json body.

Response (200):

{ "ok": true, "id": "1782968591234-9x8b3q", "tsUtcMs": 1782968591234, "pairKey": "dm-alice_bob", "peerLogin": "bob" }

Mark a thread read

Response (200):

{ "ok": true, "unread": 0 }

Unread count (for a badge)

Response (200):

{ "self": "alice", "unread": 3, "dms": 2 }

Real-time WebSocket push

For live delivery without polling: mint a single-use ticket over REST, then open a WebSocket. Tickets expire after 60 seconds and can be redeemed once. This avoids putting the bearer in a WebSocket URL (which would land in access logs).

Response (200):

{
  "ticket": "<24-byte base64url nonce>",
  "wsUrl":  "wss://phone.aloaha.com/chat-ws.ashx?ticket=<nonce>",
  "ttlSeconds": 60,
  "expiresUtc": "2026-07-02T14:24:11.000Z"
}

Server → client frames:

// On successful upgrade:
{ "type": "hello", "sid": "<server-session-id>", "tenant": "phone.aloaha.com", "login": "alice", "build": "<slug>", "serverUtc": "..." }

// On every new message to or from you (both participants’ connected devices receive it):
{
  "type": "chat-msg",
  "pairKey": "dm-alice_bob",
  "senderLogin": "bob",
  "recipientLogin": "alice",
  "message": { /* same shape as get-thread items */ }
}

Client → server frames:

// Optional keep-alive (~25 s cadence recommended); server replies with pong:
{ "type": "ping", "tsMs": 1782968591234 }

Group chats

Groups are named multi-participant threads. Members are identified by login; admins can add/remove members and rename the group; anyone can leave. list-threads, get-thread, send, mark-read, and unread-count are unified across DMs and groups — pass ?with=<peer> for a DM or ?groupId=<X> for a group.

Unified endpoints in group mode — pass ?groupId=X instead of ?with=:

GET  /chat.ashx?op=list-threads                 // both DMs and groups; group entries have kind:"group"
GET  /chat.ashx?op=get-thread&groupId=X&sinceMs=  // fetch group messages
POST /chat.ashx?op=send&groupId=X                // body { body: "..." }
POST /chat.ashx?op=mark-read&groupId=X
GET  /chat.ashx?op=unread-count                  // aggregated across DMs + groups

File attachments (images, audio, video, documents)

Attach a file to a DM or a group. Files are content-addressed by SHA-256 — if the same file is sent twice, only one copy is stored on disk. Downloads are ACL-gated to thread participants. Max 20 MB per file (enforced backend and via web.config request limit).

File-message shape (returned by get-thread, embedded in the WebSocket chat-msg frame):

{
  "id":                "1782968591234-9x8b3q",
  "tsUtcMs":           1782968591234,
  "tsUtcIso":          "2026-07-03T09:12:11.234Z",
  "senderLogin":       "alice",
  "senderDisplayName": "Alice Example",
  "kind":              "file",
  "fileSha":           "<64-hex sha256>",
  "filename":          "handoff.pdf",
  "contentType":       "application/pdf",
  "sizeBytes":         184203,
  "caption":           "signed by legal"   // optional
  // + "recipientLogin" for DMs, or "groupId" for groups
}

Errors: 400 missing file field, 403 not-a-participant, 404 peer or group not found, 413 payload > 20 MB, 415 not multipart, 429 rate-limited.

WebSocket frames — group & file additions

Additions to the chat-msg frame documented above:

// Group message (mutually exclusive with pairKey):
{
  "type": "chat-msg",
  "groupId": "g_1782968591234_a1b2",
  "senderLogin": "alice",
  "message": { /* group message body, may be text or file */ }
}

// New group created — delivered to every participant, including the creator’s other devices:
{
  "type": "group-created",
  "groupId": "g_1782968591234_a1b2",
  "name": "Ops",
  "participants": ["alice", "bob", "carol"],
  "createdBy": "alice"
}

Meeting archives (per-user, per-day, per-room)

Signed-in participants in a WebRTC room can opt to write their outgoing in-meeting chat messages to a per-user archive. This is browseable from /chat.html under “Meeting archives.” Anonymous guests are ephemeral by design — they never touch disk. Each archive is per-tenant isolated and private to the login that wrote it.

<add key="Chat:MeetingArchiveDays" value="30" />

Errors

All errors use RFC 7807 application/problem+json:

{
  "type":   "https://codeb.io/problems/rate-limited",
  "title":  "message send rate limit exceeded",
  "status": 429,
  "detail": "cap=30 refillMs=2000"
}

Common status codes: 400 missing/bad param, 401 no or invalid bearer, 404 peer not a tenant user, 413 body too large (max 32 KB, message body max 4000 chars), 429 rate-limited, 500 internal error.

Integration recipe (third-party portal)

1. Register your app as an OIDC client on the tenant (see “OIDC client management” above).
2. Drive the auth-code + PKCE flow against /oidc.ashx/authorize to obtain an access token for the signed-in user.
3. Attach Authorization: Bearer <token> to every request against /chat.ashx.
4. Bootstrap: ?op=me to resolve identity, ?op=list-threads to show the inbox, ?op=unread-count for a badge.
5. Open a WebSocket via ?op=ws-ticket + the returned wsUrl. Fall back to polling ?op=get-thread&sinceMs=<last-seen> every 3–5 s if the WS drops.
6. Send with ?op=send&with=<peer>. Handle 429 by respecting Retry-After.

Chat WebSocket — real-time frame delivery bearer + WS ticket

Mint ticket

Response (200):

{ "ticket": "<32-char-nonce>", "expiresInSec": 60 }

Open WebSocket

Server → client frames:

{"type":"hello","sid":"<12-hex>","tenant":"...","login":"...","build":"...","serverUtc":"..."}
{"type":"chat","from":"alice","body":"...","tsUtcMs":...}
{"type":"chat-deleted","msgId":"...","from":"alice","deletedAt":"..."}
{"type":"pong","sid":"...","serverUtc":"..."}

Client → server frames: only {"type":"ping"} is handled. Any other frame type is logged as RX-IGNORE and discarded. Binary frames ignored (JSON only). Max frame 8 KiB.

Errors (pre-upgrade):

• 400 not-a-websocket — non-WS request without ?build=.
• 400 missing-ticket — no ticket or length > 128.
• 401 bad-ticket — nonce unknown, expired, or already redeemed.
• 401 tenant-mismatch — ticket tenant ≠ Host header.

curl (probe only — full WS handshake needs a client library):

curl -sS -H "Authorization: Bearer <oidc-token>"      "https://phone.aloaha.com/chat.ashx?op=ws-ticket"

Chat invitations — anonymous-invited participants HMAC-signed tokens

Create invite OIDC user

Body:

{
  "channel":             "dm" | "group" | ...,     // required
  "threadKey":           "<target-thread>",        // required
  "inviteeEmail":        "guest@example.com",      // optional
  "inviteeDisplayName":  "Alice Guest",            // optional
  "scope":               "chat" | "meeting",        // default "chat"
  "ttlHours":            72                          // default 72, clamped 1..720
}

Response (200):

{ "token": "...", "hotlink": "https://<tenant>/chat-invite-accept.html?t=...",
  "nonce": "...", "expiresUtc": "...", "scope": "chat" }

Create + email invite OIDC user

Response (200):

{ "ok": true, "nonce": "...", "hotlink": "...", "expiresUtc": "...", "pickupDir": "..." }

Verify invite public

Response (200):

{ "tenant": "...", "channel": "...", "threadKey": "...",
  "inviterDisplayName": "...", "inviteeDisplayName": "...",
  "inviteeEmail": "...", "scope": "chat", "expiresUtc": "...",
  "consumed": false }

Accept invite public

Body:

{ "t": "<token>", "displayName": "Alice" }

Response (200):

{ "sessionId": "...", "tenant": "...", "channel": "...",
  "threadKey": "...", "scope": "chat", "displayName": "Alice",
  "expiresUtc": "..." }

Errors: 401 bad-invite, 409 already-consumed, 400 bad-body, 400 missing-token.

Rotate HMAC secret admin role

Response (200):

{ "ok": true, "rotated": true, "secretLen": 64 }

Stub ops OIDC user (any)

?op=list and ?op=revoke are reserved for the invitation-management UI. Both require an OIDC bearer (any authenticated user is accepted today — will be tightened to admin-only when the impls land). Current stub impls return [] / {ok:true} respectively with no I/O. Do not depend on their behaviour yet.

“Chat with us” widget origin-gated

Probe

{ "ok": true, "build": "...", "tenant": "..." }

Start session

Body:

{ "visitorName": "Alice", "visitorEmail": "alice@example.com",
  "channel": "widget"  /* optional, defaults to cfg.DefaultChannel */ }

Response (200):

{ "sessionId": "...", "threadKey": "<server-minted>",
  "channel": "widget", "expiresUtc": "..." }

Note: caller-supplied threadKey is ignored — the server always mints via WidgetSession.MintThreadKey to prevent thread-hijacking across widget sessions.

Errors: 400 missing-origin, 403 widget-disabled, 403 origin-not-allowed, 429 rate-limited.

Send message

Body:

{ "threadKey": "<must match session>", "body": "..." }

Response (200):

{ "ok": true, "messageId": "w-...", "timestampUtc": "..." }

Errors: 401 no-session, 403 origin-not-allowed, 403 origin-drift, 403 tenant-drift, 403 thread-drift, 429 rate-limited, 400 empty-body.

Poll thread

Response (200):

{ "messages": [{ "messageId": "...", "direction": "in"|"out",
    "timestampUtc": "...", "body": "...", "status": "...",
    "senderDisplayName": "Support" }],
  "serverUtc": "..." }

Email-to-chat bridge bearer (admin+)

List email threads admin

{ "threads": [{ "tenant", "channel", "threadKey", "lastMessageUtc",
    "unreadCount", "status", "participantIdentity": { ... } }] }

Get messages admin

Send email admin

Body:

{ "thread": "<defaults to 'to'>", "to": "...", "subject": "...", "body": "..." }

Poll inbox drop folder admin

{ "processed": 3, "failed": 0, "skipped": 1 }

Mark read admin

Delete thread superuser

Get/set config admin

Chat: delete message (chat.ashx addendum) bearer + sender-only

Delete a DM message

Delete a group message

Response: 204 No Content on success and on idempotent repeat (already tombstoned — a WS chat-deleted frame is still emitted so tabs that missed the first fan-out catch up).

Errors:

• 403 not-sender — only the original sender can delete.
• 403 not-a-participant — caller is not in the group participants list.
• 410 too-old — message older than 24 h (DELETE_WINDOW_MS = 24h). Detail includes ageMs.
• 404 not-found / 404 group-not-found — msg file or group meta missing.
• 400 bad-msg-id / 400 bad-group-id / 400 bad-peer / 400 self-dm.

Chat channels simulator (stub) 503 by design

Guest inbox — portal-hak PMS proxy

CodeB ships a first-class property-management-system inbox channel that lets operators reply to guest messages from the hosted PMS directly inside /chat.html. Backend /pms.ashx proxies to the tenant’s portal-hak account: list conversations, fetch a single thread, post a host-side reply. State lives entirely on the upstream PMS — the bridge stores no message bodies, only the per-tenant service credential.

Config & readiness probe

Response (200):

{
  "provider":    "portal-hak",
  "enabled":     true,
  "badge":       "Guest inbox",
  "baseUrlHint": "https://api.portal-hak.example",
  "build":       "2026-07-19-01-haip-verifier-cert"
}

curl:

curl -sS -H "Authorization: Bearer <oidc-token>" \
     "https://phone.aloaha.com/pms.ashx?op=config"

List guest conversations

Response (200):

{
  "provider": "portal-hak",
  "total":    47,
  "offset":   0,
  "limit":    200,
  "conversations": [
    {
      "id":            918273,
      "guest":         "Alice Example",
      "listingId":     "12345",
      "listingName":   "Seafront apartment, Sliema",
      "reservationId": "R-2026-0642",
      "channel":       "booking",
      "lastAt":        "2026-07-18T11:04:12Z",
      "preview":       "Hi — can we check in one hour earlier?"
    }
  ]
}

curl:

curl -sS -H "Authorization: Bearer <oidc-token>" \
     "https://phone.aloaha.com/pms.ashx?op=list-threads&limit=200&offset=0"

Fetch one thread

Response (200):

{
  "id": 918273,
  "conversation": {
    "id":            918273,
    "guest":         "Alice Example",
    "listingId":     "12345",
    "listingName":   "Seafront apartment, Sliema",
    "reservationId": "R-2026-0642",
    "channel":       "booking"
  },
  "messages": [
    {
      "id":         42,
      "from":       "guest",
      "body":       "Hi — can we check in one hour earlier?",
      "at":         "2026-07-18T11:04:12Z",
      "channel":    "booking",
      "attachments": []
    },
    {
      "id":         43,
      "from":       "host",
      "body":       "Absolutely — keys will be ready from 14:00.",
      "at":         "2026-07-18T11:07:44Z",
      "channel":    "booking",
      "attachments": []
    }
  ]
}

curl:

curl -sS -H "Authorization: Bearer <oidc-token>" \
     "https://phone.aloaha.com/pms.ashx?op=thread&id=918273"

Reply as host

Response (200):

{ "ok": true, "conversationId": 918273, "upstreamStatus": 201 }

curl:

curl -sS -X POST \
     -H "Authorization: Bearer <oidc-token>" \
     -H "Content-Type: application/json" \
     -d '{"conversationId":918273,"body":"Keys ready from 14:00."}' \
     "https://phone.aloaha.com/pms.ashx?op=reply"

Admin: get current config admin only

Response (200) — not configured:

{
  "tenant":  "phone.aloaha.com",
  "exists":  false,
  "config":  {
    "provider": "portal-hak",
    "enabled":  false,
    "baseUrl":  "",
    "auth":     { "mode": "cookie", "cookie": "" },
    "timeoutMs": 15000,
    "badge":    "Guest inbox"
  }
}

Response (200) — configured, credential set:

{
  "tenant": "phone.aloaha.com",
  "exists": true,
  "config": {
    "provider": "portal-hak",
    "enabled":  true,
    "baseUrl":  "https://portal-hak.example.com",
    "auth":     { "mode": "cookie", "cookie": "", "hasCookie": true, "hasBearer": false },
    "timeoutMs": 15000,
    "badge":    "Guest inbox"
  }
}

curl:

curl -sS -H "Authorization: Bearer <admin-oidc-token>"      "https://phone.aloaha.com/pms.ashx?op=admin-get"

Admin: save config admin only

Request body:

{
  "provider":  "portal-hak",
  "enabled":   true,
  "baseUrl":   "https://portal-hak.example.com",
  "auth":      { "mode": "cookie", "cookie": ".AspNetCore.Session=<opaque>" },
  "timeoutMs": 15000,
  "badge":     "Guest inbox"
}

Response (200):

{ "ok": true, "tenant": "phone.aloaha.com", "enabled": true }

curl:

curl -sS -X POST      -H "Authorization: Bearer <admin-oidc-token>"      -H "Content-Type: application/json"      -d @pms.json      "https://phone.aloaha.com/pms.ashx?op=admin-save"

Admin: test upstream credential admin only

Response (200) — credential works:

{
  "upstreamStatus":      200,
  "upstreamContentType": "application/json",
  "ok":                  true,
  "upstreamUser": {
    "sub":  "local:codeb",
    "name": "Heaven & Keys Ltd",
    "role": "superadmin"
  }
}

Response (200) — credential expired:

{ "upstreamStatus": 401, "upstreamContentType": "text/html", "ok": false }

curl:

curl -sS -X POST      -H "Authorization: Bearer <admin-oidc-token>"      -H "Content-Type: application/json"      -d '{"baseUrl":"https://portal-hak.example.com","auth":{"mode":"cookie","cookie":"<paste>"}}'      "https://phone.aloaha.com/pms.ashx?op=admin-test"

Build / version probe

Response (200):

{ "build": "2026-07-18-mellieha-pms-evict" }

curl:

curl -sS "https://phone.aloaha.com/pms.ashx?build=1"

Errors

All errors use RFC 7807 application/problem+json, with a type URI of shape urn:codeb:pms:<slug>:

{
  "type":   "urn:codeb:pms:not-configured",
  "title":  "PMS not configured for this tenant",
  "status": 503,
  "detail": "App_Data/<tenant>/pms.json is missing or has no service credential"
}

Common status codes:

• 401 — no or invalid bearer (urn:codeb:pms:unauthorized).
• 429 — per-operator rate-limit exceeded (60 req/min) (urn:codeb:pms:rate-limited).
• 503 — tenant PMS not configured (urn:codeb:pms:not-configured). UI links the operator to /pms-admin.html to set up the service credential.
• 502 — upstream portal-hak API returned an error or timed out (urn:codeb:pms:upstream-error).
• 413 — body exceeds the 8 KB reply cap.

Integration recipe (third-party portal)

1. Configure the tenant’s portal-hak service credential via /pms-admin.html (superadmin) — stored in App_Data/<tenant>/pms.json.
2. Probe ?op=config to decide whether the inbox tab should render for this tenant.
3. Attach Authorization: Bearer <token> minted from the tenant’s own OIDC issuer to every REST call.
4. Bootstrap: ?op=list-threads&limit=200 to populate the inbox; poll every ~30 s while the tab is the active view.
5. On row click: ?op=thread&id=<id> to fetch messages. Render from:"host" as your own-message bubble, from:"guest" as the peer bubble.
6. On reply: POST ?op=reply with { conversationId, body }. On 200, re-fetch the thread to pick up the just-persisted host message.
7. Handle 429 by respecting Retry-After; handle 401 by re-driving the OIDC sign-in.

SIPS — SIP-over-TLS listeners (RFC 5630)

The bridge accepts encrypted SIP signalling on two dedicated TLS ports, mirroring the existing UDP topology so existing SIP infrastructure can adopt SIPS without re-architecting routing.

Per-tenant certificate via SNI

Each TLS handshake selects the per-tenant cert from LocalMachine\My by SNI server name. Same cert store the WSS listener and TURN-TLS already use; same per-tenant LE cert auto-deployed via /acquire-cert (or wacs.exe directly). Adding tenant N+1 means installing one more cert in the store — no SAN-list reissue, no operator-visible SIPS reconfiguration.

Per-tenant SNI works on .NET Framework 4.8 via a manual ClientHello peek before SslStream wrapping: the bridge reads the SNI extension at the TCP layer, picks the right cert, then runs the legacy AuthenticateAsServerAsync overload — SslStream re-reads the same ClientHello bytes (we never consumed them) and the handshake completes against the right cert.

Defences shared with TURN

• ACL gate (per-IP / CIDR). The same acl.html entries that block SIP over UDP block SIPS too — SIPS traffic enters the same InboundDispatcher.HandleSipRequest dispatch point, so all existing rules apply with no per-protocol carve-out.
• Per-IP TLS auto-blacklist. Same shape as the TURN auto-blacklist: more than 5 failed handshakes from one IP in a 5-minute window blocks that IP at the SIPS accept layer for 1 hour. Private / loopback / link-local IPs never blocked. Counts AuthenticationException, IOException, and unexpected handshake errors (catches malformed ClientHello variants).
• 15 s handshake timeout. Slow-loris peers that dribble bytes after the TLS record header are torn down rather than parking a thread-pool slot indefinitely.

Observability

Three log prefixes; grep one to see the whole SIPS picture:

• [sips-arrival] — per inbound SIPS request (INF). Includes CallID for correlation with the existing [sip-trace] outbound lines.
• [sips-downgrade] — per call where an inbound sips: leg bridges to a plain sip: outbound leg (WRN). Stefan's design choice: allow + log, never silently reject — some downstream legs can't be TLS, the operator must see when it happens.
• [SIPS-chan] heartbeat — every 30 s, "N TLS handshake(s) completed in last 30s, M total since bridge start". Negative-control diagnostic for the SIPS read-loop handoff.

SIPS ↔ sip: scheme bridging policy

When a SIPS call enters and the outbound leg can only be reached via plain SIP (typical for carrier trunks), the bridge proceeds with the call and emits one [sips-downgrade] WRN per call with full correlation IDs (callId, tenant, bridge, inUri, outUri, remote). No silent downgrade, no 488 Not Acceptable Here reject — the wholesale-shaped model accepts that not every leg can be TLS but never lets it be invisible to operators.

Health endpoint: /sip-tls/health

Read-only JSON snapshot of bridge-global SIPS listener state. No HMAC or auth (mirrors /sip-ws/health and /sfu/health). Cert thumbprints and port numbers are already public via TLS handshake, and the auto-blacklist policy is intentionally surfaced so operators can plan capacity.

Response fields:

Observability: [SIPS-stats] log line (every 30 s)

Bridge emits one INF line per 30 s tick with the same counters in greppable shape:

[SIPS-stats] handshakes(ok=N delta30s=D) tls(hsFail=F autoBlk=A activeBlks=C) policy(threshold=15/5min ttl=1h)

• handshakes.ok — lifetime successful TLS handshakes
• handshakes.delta30s — new successful handshakes in the last 30 s window
• tls.hsFail — lifetime handshake failures recorded by the tracker
• tls.autoBlk — lifetime IPs ever auto-blocked (cumulative)
• tls.activeBlks — size of the current live blocklist (1-hour expiry per entry)

No REST endpoints publicly exposed for SIPS configuration. Operator controls SIPS via Sip.Sips.{Enabled,TrunkPort,PublicPort} in bridge appsettings.json (per-tenant override via WebRtcTenantSettings in a future phase).

SRTP via SDES (per-trunk, RFC 4568)

Trunk-leg media encryption is configured per trunk in the same admin surface as the Tls / TlsPort SIPS fields. When the Srtp boolean is true on a trunk, outbound INVITEs offer SDES with the AES_CM_128_HMAC_SHA1_80 crypto suite (RFC 4568 mandatory baseline); inbound INVITEs from any trunk answer SDES whenever the peer offers a=crypto: (asymmetric, safe-by-default).

Pair Tls=true + Srtp=true on the same trunk for end-to-end-on-the-carrier-leg encryption: SIPS (RFC 5630) on the signalling plane, SDES (RFC 4568) on the media plane. The bridge terminates SDES, so AI receptionist, recording, transcription and lawful-intercept hooks continue to operate; the WebRTC browser leg keeps its own DTLS-SRTP.

Audit log

Read identity and authentication events for this tenant — sign-ins (password / passkey / EU Wallet / magic link), recovery attempts, token revocations, and EU Wallet verifier interactions. The same data that powers the admin browser at /audit-log.html, exposed as a paginated JSON list for SIEM / Splunk / Datadog polling.

Query parameters (all optional):

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aloaha.com/api.ashx/v1/auditlog?event=maglink&limit=20"

Response (200):

{
  "data": [
    {
      "ts":     "2026-06-12T00:15:00.123Z",
      "event":  "maglink-finish",
      "tenant": "www.aloaha.com",
      "user":   "alice@example.com",
      "ip":     "195.158.111.88",
      "ua":     "Mozilla/5.0 (iPhone)",
      "extra":  "tenant=www.aloaha.com result=ok jti=abc123..."
    },
    {
      "ts":     "2026-06-12T00:14:42.000Z",
      "event":  "passkey-signin-ok",
      "tenant": "www.aloaha.com",
      "user":   "bob",
      "ip":     "10.0.0.42",
      "ua":     "Mozilla/5.0",
      "extra":  "credentialId=Zm9vYmFy..."
    }
  ],
  "total":  2,
  "limit":  20,
  "offset": 0,
  "next":   null
}

Each item carries the standard LogOidc shape: ts (ISO 8601 UTC), event (the canonical event name — not the URL action name, e.g. maglink-start not magic-link-start), tenant (Host-scoped, matches your bearer’s tenant), user (sub or email), ip (full IPv4 / IPv6 of the originator), ua (User-Agent string), and extra (free-form key=value tail with everything the event handler emitted).

Event taxonomy (the common ones)

For the complete list query the live event names directly: GET /v1/auditlog?limit=500 and inspect the distinct event values.

{
  "state": "ok",
  "fetched_utc": "2026-07-12T08:00:12Z",
  "source_url": "https://ec.europa.eu/tools/lotl/eu-lotl.xml",
  "lotl_bytes": 218473,
  "lotl_sha256": "a1b2c3...",
  "ms_pointers_found": 27,
  "total_anchors": 483,
  "countries": { "DE": 62, "FR": 41, "IT": 33, ... },
  "iter": 2,
  "refresh_in_flight": false,
  "per_ms": [
    { "country": "DE", "source_url": "https://...", "bytes": 84210, "sha256": "...", "anchor_count": 62 },
    ...
  ]
}

{
  "count": 62,
  "country_filter": "DE",
  "anchors": [
    { "country": "DE", "sha256": "e4a7...", "size_bytes": 1247, "file": "001_e4a70000.cer" },
    ...
  ]
}

Content-Type: application/entity-statement+jwt
Cache-Control: public, max-age=3600

{
  "iss": "https://phone.aloaha.com",
  "sub": "https://phone.aloaha.com",
  "iat": 1721376000,
  "exp": 1721379600,
  "jwks": { "keys": [ { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "kid": "..." } ] },
  "metadata": {
    "openid_provider":      { "issuer": "https://phone.aloaha.com", "jwks_uri": ".../oidc.ashx?action=jwks", ... },
    "openid_relying_party": { "vp_formats_supported": { ... }, "client_registration_types": [ "automatic" ], ... }
  },
  "authority_hints": []
}

python testscripts/openid-federation-probe.py https://phone.aloaha.com

{
  "tenant": "phone.aloaha.com",
  "count": 3,
  "limit": 500,
  "since": null,
  "events": [
    { "ts": "2026-07-12T09:14:33.421Z", "event": "vp-sso-minted", "peerId": "s_ab12", "ip": "46.11.x.x", "extra": "user=alice" },
    { "ts": "2026-07-12T09:14:33.117Z", "event": "vp-verify-result", "peerId": "s_ab12", "ip": "46.11.x.x", "extra": "verified=true iter=1 disclosures=3" },
    { "ts": "2026-07-12T09:14:22.008Z", "event": "vp-start",          "peerId": "s_ab12", "ip": "46.11.x.x", "extra": "prefix=x509_hash nonce_len=32 ttl=300" }
  ]
}

{
  "client_id": "example-saas-app",
  "tenant":    "phone.aloaha.com",
  "cert_pem":  "-----BEGIN CERTIFICATE-----\n...",
  "ca_pem":    "-----BEGIN CERTIFICATE-----\n...",
  "expires_utc": "2026-10-10T09:14:33Z",
  "days_valid": 90,
  "pfx_base64": "MIIF...",
  "pfx_password": "<24-char URL-safe random>"
}

{
  "offer_id": "5f8e2c9a7bfd3110",
  "offer_uri": "https://phone.aloaha.com/vci.ashx?offer=5f8e2c9a7bfd3110",
  "deep_link": "openid-credential-offer://?credential_offer_uri=...",
  "pre_authorized_code": "<32-byte URL-safe random, shown ONCE>",
  "expires_utc": "2026-07-19T09:14:33Z"
}

grant_type=urn:ietf:params:oauth:grant-type:pre-authorized_code&pre-authorized_code=<code>

{
  "access_token": "<32-byte URL-safe random>",
  "token_type": "Bearer",
  "expires_in": 300,
  "c_nonce": "<16-byte URL-safe random>",
  "c_nonce_expires_in": 300
}

{
  "format": "dc+sd-jwt",
  "vct": "https://example.org/membership/1.0",
  "proof": {                                <!-- optional but recommended -->
    "proof_type": "jwt",
    "jwt": "<compact JWS: header has typ=openid4vci-proof+jwt, jwk; payload has aud=<issuer>, nonce=<c_nonce from /token>, iat>"
  }
}

{
  "credential": "eyJ...jwt...bA~eyJ...disclosure1...~eyJ...disclosure2...~",
  "format": "dc+sd-jwt"
}

{
  "request_uri": "urn:ietf:params:oauth:request_uri:<opaque>",
  "expires_in": 60
}

Location: <redirect_uri>?code=<opaque>&state=<echoed>&iss=<issuer_url>

{
  "format":  "mso_mdoc",
  "doctype": "eu.europa.ec.eudi.pid.1",
  "proof": {
    "proof_type": "jwt",
    "jwt": "<compact JWS: header alg=ES256, typ=openid4vci-proof+jwt, jwk; payload aud=<issuer>, iat, nonce=<c_nonce>>"
  }
}

{
  "format":  "mso_mdoc",
  "doctype": "eu.europa.ec.eudi.pid.1",
  "proof": {
    "proof_type": "cwt",
    "cwt": "<base64url COSE_Sign1 wrapping CBOR CWT claims: iss/aud/iat + holder COSE_Key in unprotected header label -25>"
  }
}

{
  "credential": "<base64url mDoc bytes>",
  "format":     "mso_mdoc"
}

{
  "authorization_endpoint":                     "https://<tenant>/vci.ashx?authorize",
  "pushed_authorization_request_endpoint":      "https://<tenant>/vci.ashx?par",
  "require_pushed_authorization_requests":      false,
  "grant_types_supported": [
    "authorization_code",
    "urn:ietf:params:oauth:grant-type:pre-authorized_code"
  ],
  "response_types_supported":                  ["code"],
  "code_challenge_methods_supported":           ["S256"],
  "token_endpoint_auth_methods_supported":      ["none"]
}

{
  "_schema": "https://phone.codeb.io/openapi.json#/components/schemas/WalletClientsConfig",
  "_notes": "Per-tenant wallet client_id whitelist. Auto-created with defaults on first credential-issuance request.",
  "client_ids": [
    "aloaha-web-wallet",
    "some-other-wallet-vendor-id"
  ]
}

{
  "tenant":     "phone.example.com",
  "client_ids": [ "aloaha-web-wallet" ],
  "source":     "auto-created",   // one of: "auto-created" | "file" | "fallback"
  "loaded_at":  "2026-07-21T09:14:22.1234567Z"
}

Live API description

The endpoint GET /api.ashx/v1 (no auth required) returns a machine-readable description of every route. Point your OpenAPI generator or scaffolding tool at it:

curl https://www.aloaha.com/api.ashx/v1

Response (200):

{
  "name":    "CodeB Platform REST API",
  "version": "v1",
  "endpoints": [
    { "method": "POST",  "path": "/api.ashx/v1/calls",                "description": "Initiate an outbound AI call",        "area": "outbound-ai" },
    { "method": "GET",   "path": "/api.ashx/v1/calls",                "description": "List outbound AI calls",              "area": "outbound-ai" },
    { "method": "GET",   "path": "/api.ashx/v1/calls/{id}",           "description": "Get one call's status + outcome",     "area": "outbound-ai" },
    { "method": "POST",  "path": "/api.ashx/v1/calls/{id}/hangup",    "description": "Cancel/terminate a call",             "area": "outbound-ai" },
    { "method": "GET",   "path": "/api.ashx/v1/numbers",              "description": "List virtual numbers",                "area": "numbers" },
    { "method": "GET",   "path": "/api.ashx/v1/transcripts",          "description": "List transcripts",                    "area": "transcripts" },
    { "method": "GET",   "path": "/api.ashx/v1/transcripts/{callId}", "description": "Get full transcript by callId",       "area": "transcripts" },
    { "method": "GET",   "path": "/api.ashx/v1/inbound-routes",       "description": "List inbound DID routes",             "area": "inbound-routes" },
    { "method": "POST",  "path": "/api.ashx/v1/inbound-routes",       "description": "Create an inbound route",             "area": "inbound-routes" },
    { "method": "GET",   "path": "/api.ashx/v1/inbound-routes/{did}", "description": "Get one inbound route by DID",        "area": "inbound-routes" },
    { "method": "DELETE","path": "/api.ashx/v1/inbound-routes/{did}", "description": "Delete one inbound route by DID",     "area": "inbound-routes" },
    { "method": "PUT",   "path": "/api.ashx/v1/inbound-routes/{did}", "description": "Update one inbound route\u0027s User",   "area": "inbound-routes" },
    { "method": "GET",   "path": "/api.ashx/v1/webhooks",             "description": "List webhook subscriptions",          "area": "webhooks" },
    { "method": "GET",   "path": "/api.ashx/v1/auditlog",             "description": "List identity/auth events (audit log)","area": "auditlog" }
  ],
  "auth":       "Authorization: Bearer <token>. token = OIDC access token (role=admin) OR an ak_-prefixed API key minted via /api-keys-admin.html",
  "pagination": "?limit=N&offset=M  (defaults 50, 0)",
  "errors":     "{ error: <code>, error_description: <text> }"
}

Coming soon

v2 will add: dedicated API keys (so integrators don’t need to use admin user credentials), inbound-route CRUD, contact lists, scheduled-campaign primitives. The platform positioning sits on the self-hosted CPaaS page. If a missing endpoint is blocking you, tell us.