Let your users buy a phone number through your app

Voiceself-service number provisioning for tenants

Give each customer their own project and API token, then search, buy, route and release phone numbers with their credentials rather than yours.

restmulti-tenant

The claim

Your app onboards a customer with two requests of yours, and then acts as them. POST /api/projects creates their subproject, POST /api/project/tokens issues a token bound to it, and every number request after that travels on a second RestClient built from that project id and token.

Why it holds

The permissions are exactly the list you pass. This tenant gets numbers, calling and messaging, and management is deliberately absent. The spec’s Project.TokenPermission enum is the whole vocabulary. Each phone number operation here documents the Numbers scope, and both onboarding operations document Management.

A stored record with no token raises. A missing credential is never quietly replaced by yours, which matters because RestClient() falls back to the environment when an argument is empty.

How it works

platform = RestClient()          # your credentials, used for onboarding only

def as_tenant(record):
    if not record.get("project_id") or not record.get("token"):
        raise ValueError("no tenant credentials; refusing to act as the platform")
    return RestClient(project=record["project_id"], token=record["token"],
                      host=SPACE)

def buy(record, number, webhook_url):
    client = as_tenant(record)
    bought = client.phone_numbers.create(number=number)
    client.phone_numbers.update(bought["id"], name=record["name"],
                                call_handler="relay_script",
                                call_relay_script_url=webhook_url)
    return bought

RestClient(project, token, host) builds its own HttpClient, whose session carries that pair as basic auth (rest/client.py). Two clients in one process are two identities. The tenant’s requests are GET /api/relay/rest/phone_numbers/search, POST /api/relay/rest/phone_numbers with the required number, PUT and DELETE on /api/relay/rest/phone_numbers/{id}.

3.0.1 wraps the tokens path as client.project.tokens but has no wrapper for POST /api/projects, so that one request goes through client._http, the shared HttpClient every namespace holds.

The spec documents no GET for tokens, so the value is read from the create response and stored then. The response’s id is stored beside it, because PATCH and DELETE /api/project/tokens/{token_id} are how a credential is rotated or revoked and nothing lists them. tenants.json stands in for the table where you keep it. It holds a live credential, so it is in .gitignore; in your app that row belongs in your database, encrypted.

Limitations

The verifier proves who sends what, not what the platform allows. The spec documents 401 on each of these operations for a request it will not authenticate.

numbers reads one page. The list endpoint pages with page_size and page_token. A tenant holding more numbers than one page needs the loop this recipe does not write.

Releasing a number is not reversible, and the same number may not be available to buy again. The create response for the subproject also carries a one time signing_key, which this recipe does not keep.

What to change first

Delete the token check in as_tenant and run the verifier. It stops at “acted for a tenant with no credentials”. That is the point: with the check gone, RestClient falls back to the environment and sends the request as you.

Where this sits

Before this

Isolate tenants with subprojects and scoped tokens Buy a number and point it at your app

python/app.py

"""Let your users buy a phone number through your app.

Onboarding uses your credentials: `POST /api/projects` creates the tenant's
subproject and `POST /api/project/tokens` issues a token bound to it. Every
number request after that goes through a second RestClient built from the
tenant's own credentials, so your platform token is never used on their behalf.

Written against signalwire-sdk 3.0.1 (RestClient, RestClient.phone_numbers).

    python app.py onboard "Acme Dental"
    python app.py offer "Acme Dental" 415
    python app.py buy "Acme Dental" +14155550123 https://your-host/acme/
    python app.py numbers "Acme Dental"
    python app.py release "Acme Dental" <number_id>
"""
import json
import os
import sys
from pathlib import Path

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# your own credentials, used for onboarding and nothing else
platform = RestClient()
SPACE = os.environ["SIGNALWIRE_SPACE"]

# stands in for the table where you keep each tenant's credentials
TENANTS_PATH = Path(os.getenv("TENANTS_PATH", "tenants.json"))

# what a tenant's token may do. management is deliberately absent, so the token
# cannot create further projects or tokens
PERMISSIONS = ["numbers", "calling", "messaging"]


def _load():
    if not TENANTS_PATH.exists():
        return {}
    return json.loads(TENANTS_PATH.read_text(encoding="utf-8"))


def _save(tenants):
    tmp = TENANTS_PATH.with_suffix(".tmp")
    tmp.write_text(json.dumps(tenants, indent=2), encoding="utf-8")
    os.replace(tmp, TENANTS_PATH)


def onboard(name, permissions=PERMISSIONS):
    """Create the tenant's subproject and a token bound to it. Stores both."""
    # 3.0.1 wraps the tokens path (client.project.tokens) but not POST
    # /api/projects, so the subproject goes through the HTTP client every
    # namespace shares (rest/client.py)
    project = platform._http.post("/api/projects",
                                  body={"name": name, "force_https_requests": True})
    token = platform.project.tokens.create(name=f"{name} numbers",
                                           permissions=list(permissions),
                                           subproject_id=project["id"])
    # token_id is the only handle for PATCH or DELETE later: the spec
    # documents no way to list a project's tokens
    record = {"name": name, "project_id": project["id"], "token_id": token["id"],
              "permissions": token["permissions"], "token": token["token"]}
    tenants = _load()
    tenants[name] = record
    # the token is shown once, so it is stored here at that moment
    _save(tenants)
    return record


def tenant(name):
    """The stored record for one tenant."""
    record = _load().get(name)
    if record is None:
        raise KeyError(f"{name} has not been onboarded")
    return record


def as_tenant(record):
    """A client that authenticates as the tenant. Never falls back to yours."""
    if not record.get("project_id") or not record.get("token"):
        raise ValueError("no tenant credentials; refusing to act as the platform")
    return RestClient(project=record["project_id"], token=record["token"],
                      host=SPACE)


def offer(record, areacode, max_results=5):
    """Numbers the tenant can pick from. Returns E.164 strings."""
    found = as_tenant(record).phone_numbers.search(areacode=areacode,
                                                   number_type="local",
                                                   max_results=max_results)
    return [n["number"] for n in found.get("data", [])]


def buy(record, number, webhook_url):
    """Purchase the number into the tenant's subproject and point it at them."""
    client = as_tenant(record)
    bought = client.phone_numbers.create(number=number)
    client.phone_numbers.update(bought["id"], name=record["name"],
                                call_handler="relay_script",
                                call_relay_script_url=webhook_url)
    return bought


def numbers(record):
    """The first page of the tenant's numbers. Page with `page_size`."""
    return as_tenant(record).phone_numbers.list()


def release(record, number_id):
    """Give the number back when the tenant cancels."""
    return as_tenant(record).phone_numbers.delete(number_id)


if __name__ == "__main__":
    args = sys.argv[1:]
    cmd = args[0] if args else "help"
    rest = args[1:]
    if not rest:
        print(__doc__)
    elif cmd == "onboard":
        print(onboard(rest[0]))
    elif cmd == "offer":
        for number in offer(tenant(rest[0]), rest[1]):
            print(number)
    elif cmd == "buy":
        print(buy(tenant(rest[0]), rest[1], rest[2]))
    elif cmd == "numbers":
        print(numbers(tenant(rest[0])))
    elif cmd == "release":
        print(release(tenant(rest[0]), rest[1]))
    else:
        print(__doc__)

/**
 * Let your users buy a phone number through your app.
 *
 * Onboarding uses your credentials: `POST /api/projects` creates the tenant's
 * subproject and `POST /api/project/tokens` issues a token bound to it. Every
 * number request after that goes through a second RestClient built from the
 * tenant's own credentials, so your platform token is never used on their
 * behalf.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient, RestClient.phoneNumbers).
 *
 *     npm start onboard "Acme Dental"
 *     npm start buy "Acme Dental" +14155550123 https://your-host/acme/
 */
import "dotenv/config";
import { readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
import { RestClient } from "@signalwire/sdk";

// your own credentials, used for onboarding and nothing else
export const platform = new RestClient();
const SPACE = process.env["SIGNALWIRE_SPACE"] ?? "";

// stands in for the table where you keep each tenant's credentials
export const TENANTS_PATH = process.env["TENANTS_PATH"] ?? "tenants.json";

// what a tenant's token may do. management is deliberately absent, so the token
// cannot create further projects or tokens
export const PERMISSIONS = ["numbers", "calling", "messaging"];

export type Tenant = {
  name: string; project_id: string; token_id: string;
  permissions: string[]; token: string;
};

function load(): Record<string, Tenant> {
  if (!existsSync(TENANTS_PATH)) return {};
  return JSON.parse(readFileSync(TENANTS_PATH, "utf-8"));
}

function save(tenants: Record<string, Tenant>) {
  const tmp = `${TENANTS_PATH}.tmp`;
  writeFileSync(tmp, JSON.stringify(tenants, null, 2), "utf-8");
  renameSync(tmp, TENANTS_PATH);
}

/** Create the tenant's subproject and a token bound to it. Stores both. */
export async function onboard(name: string, permissions = PERMISSIONS): Promise<Tenant> {
  // 2.0.5 wraps the tokens path (client.project.tokens) but not POST
  // /api/projects, so the subproject goes through the HTTP client every
  // namespace shares
  const http = (platform.calling as unknown as {
    _http: { post(path: string, body: unknown): Promise<Record<string, string>> };
  })._http;
  const project = await http.post("/api/projects",
                                  { name, force_https_requests: true });
  const token = await platform.project.tokens.create({
    name: `${name} numbers`, permissions: [...permissions], subproject_id: project["id"],
  });
  // token_id is the only handle for PATCH or DELETE later: the spec documents
  // no way to list a project's tokens
  const record: Tenant = {
    name, project_id: project["id"] as string, token_id: token["id"],
    permissions: token["permissions"], token: token["token"],
  };
  const tenants = load();
  tenants[name] = record;
  // the token is shown once, so it is stored here at that moment
  save(tenants);
  return record;
}

/** The stored record for one tenant. */
export function tenant(name: string): Tenant {
  const record = load()[name];
  if (!record) throw new Error(`${name} has not been onboarded`);
  return record;
}

/** A client that authenticates as the tenant. Never falls back to yours. */
export function asTenant(record: Partial<Tenant>): RestClient {
  if (!record.project_id || !record.token) {
    throw new Error("no tenant credentials; refusing to act as the platform");
  }
  return new RestClient({ project: record.project_id, token: record.token, host: SPACE });
}

/** Numbers the tenant can pick from. Returns E.164 strings. */
export async function offer(record: Tenant, areacode: string, maxResults = 5) {
  // the spec's query param is `areacode`, all lower case. The SDK passes the
  // keys through, so a camelCase one would travel undocumented
  const found = await asTenant(record).phoneNumbers.search({
    areacode, number_type: "local", max_results: maxResults,
  });
  return (found["data"] ?? []).map((n: Record<string, string>) => n["number"]);
}

/** Purchase the number into the tenant's subproject and point it at them. */
export async function buy(record: Tenant, number: string, webhookUrl: string) {
  const client = asTenant(record);
  const bought = await client.phoneNumbers.create({ number });
  await client.phoneNumbers.update(bought["id"], {
    name: record.name, call_handler: "relay_script", call_relay_script_url: webhookUrl,
  });
  return bought;
}

/** The first page of the tenant's numbers. Page with `page_size`. */
export function numbers(record: Tenant) {
  return asTenant(record).phoneNumbers.list();
}

/** Give the number back when the tenant cancels. */
export function release(record: Tenant, numberId: string) {
  return asTenant(record).phoneNumbers.delete(numberId);
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, name, ...rest] = process.argv.slice(2);
  if (!name) {
    console.log("usage: npm start <onboard|offer|buy|numbers|release> <tenant> [args]");
  } else if (cmd === "onboard") {
    console.log(await onboard(name));
  } else if (cmd === "offer") {
    for (const n of await offer(tenant(name), rest[0])) console.log(n);
  } else if (cmd === "buy") {
    console.log(await buy(tenant(name), rest[0], rest[1]));
  } else if (cmd === "numbers") {
    console.log(await numbers(tenant(name)));
  } else if (cmd === "release") {
    console.log(await release(tenant(name), rest[0]));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # your project id, API token, space
python app.py onboard "Acme Dental"
python app.py offer "Acme Dental" 415
python app.py buy "Acme Dental" +14155550123 https://your-host/acme/
python app.py numbers "Acme Dental"
python app.py release "Acme Dental" <number_id>

The TypeScript surface is the same five commands on @signalwire/sdk:

cd typescript
npm ci
cp ../.env.example .env
npm start onboard "Acme Dental"

Your credentials must be a root project’s. The spec says creating a project is allowed only when authenticated as a top level project, and a subproject that tries fails with 422 nested_subprojects_not_allowed.

Buying a number is a billable action, so run offer first and buy a number you mean to keep. There is no server to expose. The handler URL you pass to buy is where inbound calls on that number will fetch their document.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier gives each client its own recorder and asserts the following.

the recipe’s permission list is the one the verifier expects, every value is in the spec’s enum, numbers is in it and management is not
onboarding sends POST /api/projects and POST /api/project/tokens, with the exact bodies, on the platform client
the stored record carries the project id, the token and the token id, and survives as a file
the spec documents PATCH and DELETE for a token id, and no GET that would list tokens
a record with an empty token, or an empty project id, raises and builds no client
the four clients built afterwards all carry the tenant’s basic-auth pair and the space host
the platform client, with every namespace recorded, sends no number request at all
the tenant client sends the search, the purchase, the update, the list and the release, in that order, with documented paths, query params and bodies
the call_handler sent is in the spec’s PhoneNumberCallHandlerRequest enum
buy returns the purchase response rather than the handler update that follows it
the TypeScript surface sends the same requests, and each one carries the basic-auth pair it would go out with: the platform’s for onboarding, the tenant’s for all five number requests

Report an issue