Third Party Login

With third party login, you can use the admin credentials to obtain a session id for a particular domain or user and use that id to log into that domain or user of the PBX from another webpage (URL) other than the PBX. That is very useful when you want to access the PBX through links from another site.

The admin password never leaves your server: the server obtains a session id from the PBX and passes only that id to the browser.

How it works (version 70 and later)

Since version 70, the PBX login page (welcome.htm) accepts a session URL parameter and sets it directly as the session cookie. This makes the flow simple:

Your server requests a temporary token from the PBX using the admin credentials:

POST /rest/system/session HTTP/1.1
Authorization: Basic base64encode(admin:password)
Content-Type: application/json

{ "name": "3rd", "admin": true }

Variants for scoping the session:

{ "name": "3rd", "admin": true, "domain": "domain.com" }   → admin session for a domain
{ "name": "3rd", "domain": "domain.com" }                  → domain portal session
{ "name": "3rd", "username": "40", "domain": "domain.com" }→ session for extension 40

The response body is the temporary token as a JSON string, for example "c8ewp9r0jisr9saqovhx".

Your server exchanges the temporary token for a real session id. The token is only valid for about 10 seconds and for a single use, so do this immediately:
```
POST /rest/system/session HTTP/1.1
Content-Type: application/json

{ "name": "session", "value": "<temporary token>" }
```
No Authorization header is needed here. The response carries the real session id in a Set-Cookie header:
```
Set-Cookie: session=74evcdn9bplvg53irvfb; Path=/; SameSite=Strict; Secure; HttpOnly
```
The browser is redirected to the PBX login page with that session id:
```
https://YOUR_PBX_URL/welcome.htm?session=74evcdn9bplvg53irvfb
```
welcome.htm sets the id as the session cookie, removes it from the URL, and forwards the user to the right page automatically — the admin dashboard, the domain portal, or the user portal, depending on how the session was scoped in step 1.

caution

The id issued in step 2 is a live session credential, not a short-lived token. Generate it at click time, pass it to the browser immediately, and never store or log it.

Server-side example (Node.js)

An Express handler that performs steps 1 and 2 and returns the login URL to the client. Make sure the request is authenticated by your application before minting a session — anyone who can call this endpoint can log into the PBX.

import express from 'express';

const app = express();
app.use(express.json());

const PBX_URL = 'https://pbx.xyz.com';
const PBX_ADMIN = 'admin';
const PBX_PASSWORD = 'secret';

app.post('/pbx-login', async (req, res) => {
  // Make sure this request is authenticated by your own application first!

  // Step 1: temporary token (valid ~10 seconds)
  const mint = await fetch(`${PBX_URL}/rest/system/session`, {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' +
        Buffer.from(`${PBX_ADMIN}:${PBX_PASSWORD}`).toString('base64'),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: '3rd', admin: true })
  });
  if (!mint.ok) return res.status(502).json({ error: 'Could not create token' });
  const token = (await mint.text()).replace(/"/g, '');

  // Step 2: exchange the token for a real session id (no auth header)
  const activate = await fetch(`${PBX_URL}/rest/system/session`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'session', value: token })
  });
  const setCookie = activate.headers.get('set-cookie') || '';
  const sessionId = (setCookie.match(/session=([^;]+)/) || [])[1];
  if (!sessionId) return res.status(502).json({ error: 'Could not activate session' });

  // Step 3: hand the login URL to the browser
  res.json({ url: `${PBX_URL}/welcome.htm?session=${sessionId}` });
});

On the client, open the returned URL — for example:

const response = await fetch('/pbx-login', { method: 'POST' });
const { url } = await response.json();
window.open(url, '_blank');

The user lands in the PBX, already logged in.

Versions 69 and older

On version 69 and older, welcome.htm does not process the session URL parameter. On these versions the browser itself must perform the token exchange (step 2 above) against the PBX, because the resulting session cookie has to be set in the browser by the PBX (same-origin).

The flow is the same as documented above, except:

Your server performs only step 1 and passes the temporary token (not an activated session id) to the browser.
A page served by the PBX itself reads the token, performs the step 2 POST /rest/system/session with { "name": "session", "value": token }, and then navigates to thirdparty.htm. Because the page is same-origin with the PBX, the session cookie is set correctly.
Such a page can be installed as a custom page in the pbxwebai folder inside the PBX working directory (for example /usr/local/pbx/pbxwebai/ on a default installation). Note that the PBX's Content-Security-Policy does not allow inline scripts on custom pages, so the activation logic must live in an external .js file loaded with <script src>.

Remember: the temporary token must be used within about 10 seconds of being issued, so it should be generated at the moment the user clicks the login link.

Third Party Login

How it works (version 70 and later)​

Server-side example (Node.js)​

Versions 69 and older​

How it works (version 70 and later)

Server-side example (Node.js)

Versions 69 and older