Skip to main content

OAuth connections

Some connectors sign in to the other system with OAuth 2.0 instead of a pasted token. MonoPbx keeps one OAuth connection per installed connector, refreshes it before it expires and tells you when you must sign in again.

You manage connections in Admin > Settings > Integrations > Integrations (/admin/integrations). Seeing the status needs integrations:read. Connect, Reconnect and Disconnect need integrations:write.

Connect​

  1. Install the connector in Integrations and fill in its settings.
  2. Press Connect. The browser goes to the other system to sign in.
  3. Allow the access. The browser returns to /admin/integrations/oauth/callback and the status shows Connected, with the time the token is valid until.

The sign-in uses the authorization code flow with PKCE (S256). A pending sign-in is valid for ten minutes and works once. A sign-in that expired, was used already or belongs to another company is refused: press Connect again.

The Connect button is shown only for connectors that have an OAuth provider on your PBX. The operator registers MonoPbx as an app with each system and lists it in the provider file named by MPBX_INTEGRATIONS_OAUTH_FILE; the redirect address to register is https://<your PBX>/admin/integrations/oauth/callback.

The operator can list the providers in mpbx.toml instead of a separate file. The endpoints and scopes of the common systems come with MonoPbx, so an entry needs only the connector, the client id and the redirect address; the client secret is read from a file the entry names or from the environment, never written into mpbx.toml:

[[integrations.oauth]]
connector = "hubspot"
client_id = "your-client-id"
redirect_uri = "https://pbx.example.com/admin/integrations/oauth/callback"
client_secret_file = "/run/secrets/hubspot_client_secret"

Providers in the file named by MPBX_INTEGRATIONS_OAUTH_FILE keep working; when a connector is listed in both, mpbx.toml wins.

Status​

StatusMeaning
Not connectedNo sign-in.
ConnectedThe tokens work.
Sign in againThe other system permanently refused to renew the tokens (for example invalid_grant, invalid_client or a 401 answer). Press Reconnect.

MonoPbx renews the access token about five minutes before it expires (at most half its lifetime) and keeps a refresh token the other system rotates. A temporary failure keeps the old token and is retried after 1, 2, 4 minutes and so on, up to an hour. A permanent refusal sets Sign in again and raises the integration.needs_reconnect event, which you can receive on the events WebSocket and in webhooks.

Disconnect and remove​

Disconnect asks the other system to revoke the tokens, then deletes them from MonoPbx. The integration stops working until you connect again. If the other system cannot be reached, the tokens are deleted in MonoPbx anyway and the revoke is best effort. Uninstalling the integration does the same.

Tokens are sealed with your company's key. No screen or API answer ever returns one, and none is written to a log.

API​

CallPermission
GET /api/v1/integrations/installs/{id}/oauth: whether the connector signs in with OAuth here, and its connectionsintegrations:read
POST /api/v1/integrations/installs/{id}/oauth/start: the address to openintegrations:write
POST /api/v1/integrations/oauth/callback: finish the sign-in with state and codeintegrations:write
DELETE /api/v1/integrations/installs/{id}/oauth/{connection_id}: disconnectintegrations:write

Limits​

  • The console shows and starts the company's connection.
  • The sign-in addresses of a provider are fixed per connector, so a connector whose addresses depend on the account (Kommo, Bitrix24) works for one account per PBX. See Kommo, Bitrix24 and Odoo.
  • Jira, calendar sync and CRM templates keep their own sign-in.