Skip to content

ExoVoIPDeveloper guide

Tenants

Management of the companies hosted on the platform. The endpoints on this page are reserved for the platform administrator (global keys with the tenants:* scope), except GET /v1/tenants/current, which is available to every tenant.

Current tenant

With a tenant key, returns your own company's data (name, status, limits, settings). It is the simplest call to check that a key works.

curl -s https://centralino.exovoip.it/api/v1/tenants/current \
  -H "X-API-Key: $EXOPBX_API_KEY"

const { tenant } = await pbx.tenants.current();
console.log(tenant.name, tenant.status);

$out = $pbx->tenants->current();
echo $out['tenant']['name'], PHP_EOL;

tenant = pbx.tenants.current()["tenant"]
print(tenant["name"], tenant["status"])

Creating a tenant

Creation registers the company and its first administrator; the administrator's initial password is returned only once.

curl -s -X POST https://centralino.exovoip.it/api/v1/tenants \
  -H "X-API-Key: $EXOPBX_API_KEY" -H "Content-Type: application/json" \
  -d '{"code":"acme","name":"Acme S.r.l.","maxExt":20,"maxCalls":6,
       "admin":{"email":"admin@acme.example","name":"Mario Rossi"}}'

const created = await pbx.tenants.create({
  code: 'acme',
  name: 'Acme S.r.l.',
  maxExt: 20,
  maxCalls: 6,
  admin: { email: 'admin@acme.example', name: 'Mario Rossi' },
});
console.log(created.tenant.id, created.admin?.initialPassword); // password iniziale mostrata una volta

$out = $pbx->tenants->create([
    'code' => 'acme',
    'name' => 'Acme S.r.l.',
    'maxExt' => 20,
    'maxCalls' => 6,
    'admin' => ['email' => 'admin@acme.example', 'name' => 'Mario Rossi'],
]);

out = pbx.tenants.create({
    "code": "acme",
    "name": "Acme S.r.l.",
    "maxExt": 20,
    "maxCalls": 6,
    "admin": {"email": "admin@acme.example", "name": "Mario Rossi"},
})

code is the tenant's short identifier (lowercase letters and digits), also used in the phone system's internal names: choose a stable one.

Limits, suspension and reactivation

PUT /v1/tenants/:id/limits: maximum number of extensions and concurrent calls.
POST /v1/tenants/:id/suspend: the tenant remains visible but its keys and users switch to read-only.
POST /v1/tenants/:id/resume: reactivates the tenant.
DELETE /v1/tenants/:id: deactivates the tenant without deleting its data.

curl -s "https://centralino.exovoip.it/api/v1/tenants?status=active&limit=50" -H "X-API-Key: $EXOPBX_API_KEY"
curl -s -X PUT https://centralino.exovoip.it/api/v1/tenants/3/limits -H "X-API-Key: $EXOPBX_API_KEY" \
  -H "Content-Type: application/json" -d '{"maxExt":30,"maxCalls":10}'
curl -s -X POST https://centralino.exovoip.it/api/v1/tenants/3/suspend -H "X-API-Key: $EXOPBX_API_KEY" \
  -H "Content-Type: application/json" -d '{"reason":"manual"}'
curl -s -X POST https://centralino.exovoip.it/api/v1/tenants/3/resume -H "X-API-Key: $EXOPBX_API_KEY"

const { items } = await pbx.tenants.list({ status: 'active', limit: 50 });
await pbx.tenants.limits(3, { maxExt: 30, maxCalls: 10 });
await pbx.tenants.suspend(3, { reason: 'manual' });
await pbx.tenants.resume(3);

$page = $pbx->tenants->list(status: 'active', limit: 50);
$pbx->tenants->limits(3, ['maxExt' => 30, 'maxCalls' => 10]);
$pbx->tenants->suspend(3, ['reason' => 'manual']);
$pbx->tenants->resume(3);

page = pbx.tenants.list(status="active", limit=50)
pbx.tenants.limits(3, {"maxExt": 30, "maxCalls": 10})
pbx.tenants.suspend(3, {"reason": "manual"})
pbx.tenants.resume(3)

Acting on behalf of a tenant

A global key operates on a specific tenant with the X-Tenant-Id header (see Authentication). Every such access is recorded in the activity log.

# Chiave globale (piattaforma): azienda indicata con X-Tenant-Id
curl -s https://centralino.exovoip.it/api/v1/extensions \
  -H "X-API-Key: $EXOPBX_API_KEY" \
  -H "X-Tenant-Id: 3"

// Per tutto il client...
const acme = new ExoPBX({ apiKey: process.env.EXOPBX_API_KEY, tenantId: 3 });
// ...oppure per una singola richiesta
await pbx.extensions.list({ limit: 50 }, { tenantId: 3 });

$acme = new Client(['apiKey' => getenv('EXOPBX_API_KEY'), 'tenantId' => 3]);
$pbx->extensions->list(limit: 50, options: ['tenantId' => 3]);

acme = ExoPBX(tenant_id=3)
pbx.extensions.list(limit=50, tenant_id=3)

Endpoints

Request	Scope	SDK method
`GET /v1/tenants`	`tenants:read`	`tenants.list()`
`POST /v1/tenants`	`tenants:write`	`tenants.create()`
`GET /v1/tenants/current`	`extensions:read`	`tenants.current()`
`GET /v1/tenants/:id`	`tenants:read`	`tenants.get()`
`PATCH /v1/tenants/:id`	`tenants:write`	`tenants.update()`
`DELETE /v1/tenants/:id`	`tenants:write`	`tenants.delete()`
`PUT /v1/tenants/:id/limits`	`tenants:write`	`tenants.limits()`
`POST /v1/tenants/:id/suspend`	`tenants:write`	`tenants.suspend()`
`POST /v1/tenants/:id/resume`	`tenants:write`	`tenants.resume()`
`POST /v1/tenants/:id/impersonate`	`tenants:impersonate`	`tenants.impersonate()`
`GET /v1/tenants/:id/voice-node`	`tenants:read`	`tenants.getVoiceNode() · py: tenants.get_voice_node()`
`PUT /v1/tenants/:id/voice-node`	`tenants:write`	`tenants.setVoiceNode() · py: tenants.set_voice_node()`