Skip to content

Configure the REST API

The PBX API (api module) exposes UnifiedBX/Asterisk operations over HTTPS for integrations — call origination, status queries, CDR access, extension provisioning. UnifiedBX uses GraphQL for newer API; older REST endpoints exist for some operations.

Security boundary

The API can originate calls and read all CDR. Treat API tokens like passwords. Restrict by IP and rotate.

Before You Start

  • You know what your integration needs (read-only stats? originate calls? provision extensions?).
  • HTTPS is configured (API requires SSL).
  • A planned source IP for the integration (so you can firewall correctly).

Steps

Generate API credentials

  1. Go to System Admin → API.
  2. Click + New Application.
  3. Fill in:
    • Name — e.g. crmpro-integration.
    • Description — what calls it.
    • Scopes — pick the granular permissions:
      • call:read / call:write
      • cdr:read
      • extension:read / extension:write
      • voicemail:read
      • etc.
    • IP Whitelist — restrict to source IP(s) of the integration.
  4. Click Submit.
  5. Copy the Client ID and Client Secret — secret is shown ONCE. Lose it = regenerate.

Use the API

The API is at https://<unifiedbx-fqdn>/admin/api/api/.

GraphQL endpoint (preferred for new integrations):

# Get an access token (OAuth client_credentials flow):
curl -X POST https://<unifiedbx>/admin/api/api/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-client-secret>"
# Returns access_token

# Call GraphQL:
curl -X POST https://<unifiedbx>/admin/api/api/gql \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ fetchAllExtensions { extension { user { name extension } } } }"}'

GraphQL schema docs are typically at https://<unifiedbx>/admin/api/api/explorer (introspection UI).

REST endpoints (older)

For modules that haven't moved to GraphQL, REST endpoints still exist:

# Originate a call (extension 1001 calls 12075551234):
curl -X POST https://<unifiedbx>/admin/api/api/originate \
  -H "Authorization: Bearer <access_token>" \
  -d '{"channel": "PJSIP/1001", "context": "from-internal", "exten": "12075551234", "priority": 1}'

Verify

Successful auth returns a token. Sample queries return JSON with the requested data. Failures return a 401/403 with detail.

Common Issues

  • 401 Unauthorized. Wrong client_id/secret, or token expired (default lifetime ~1 hour). Re-fetch.
  • 403 Forbidden. Application doesn't have the scope. Edit application, add scope.
  • CORS errors from browser. API is server-to-server; don't call from browser JS. Proxy through your backend.
  • High latency. GraphQL introspection is slow if the schema is large. Cache where possible.
  • Rate limit. API has built-in throttling. If you hit it, throttle your client.
  • Lost client_secret. Can't recover; generate a new application and update the integration.