Freeze one request and classify the first failure
Record timestamp and timezone, client host, destination origin and path, FreePBX and API module versions, application ID, grant type, requested scope, HTTP method, content type, response status and sanitized response body. Record only a token or secret fingerprint.
Classify the first divergence: TLS or reachability failure, token endpoint not found, rejected client, invalid grant, invalid scope, token issued but GraphQL returns unauthenticated or forbidden, schema validation failure, resolver failure, or an accepted asynchronous operation that later fails.
Prove origin, TLS and endpoint before changing credentials
Resolve the exact hostname from the client and inspect the served certificate, proxy result and final API path. Distinguish a network timeout, TLS validation error, redirect, web-server denial, missing route and application-level OAuth response.
The release/17.0 implementation references /admin/api/api/token and /admin/api/api/gql; confirm the running deployment rather than assuming those paths survive a proxy rewrite. Do not disable certificate validation as a durable repair.
Match the application, grant and secret
Identify the exact API application record by non-secret ID and name. Compare the configured grant type with the request, then verify the client identifier and secret through a controlled rotation or fingerprinted secret store. A browser-user login and an API client credential are different identities.
If a newly rotated secret works, revoke the replaced credential and update its authorized consumer. Do not copy a working administrator credential into the integration or expose the raw token in diagnostic output.
Correlate requested, allowed and granted scopes
Capture the requested scope, the application allow-list and the granted token scopes as three separate records. The API implementation derives valid REST and GraphQL scopes from active modules, so a scope from another version or an inactive module can be rejected before the query runs.
If token issuance succeeds but the operation is forbidden, prove the resolver-required scope and token grant before widening access. Granting every available scope hides the failing boundary and expands impact unnecessarily.
Validate the active GraphQL schema and request shape
Run a minimal authorized query, then compare the failing operation with the active schema: operation type, field, arguments, variables and selected return fields. Separate HTTP success from a GraphQL response containing errors.
A missing field can reflect module state, version or schema composition rather than authentication. A parse or variable error should not trigger secret rotation, while an expired or revoked token should not trigger schema changes.
Follow resolver or asynchronous work to completion
For a request that passes authentication and validation, correlate the resolver, owning module and returned operation or transaction identifier with PBX logs and final status. The module metadata defines asynchronous transaction history separately from OAuth access, so token success is not operation success.
Correct only the first demonstrated boundary and repeat the same sanitized request. Preserve the prior application and scope record for rollback. This diagnostic is documentation-derived; no PBX, application, credential, token, GraphQL operation or mutation was inspected or tested.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Sangoma FreePBX PBX API documentation ↗
- FreePBX PBX API module repository ↗
- FreePBX PBX API release/17.0 module metadata ↗
- FreePBX PBX API release/17.0 implementation ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.