When to use this endpoint

Select a provider, request ret=1, then open the returned url in a browser. Complete the provider callback before checking Accounting_status. An authorization URL alone does not establish a connection.

Authentication and permissions

Use signed API-key authentication or a logged-in CRM session on the account’s routed host. API keys act as their owner; session requests require the dispatcher’s CSRF token where configured. Tenant rows and settings belong to that authenticated account.

Only Xero authorization bypasses the facade login requirement; this does not make status, logs, sync or disconnect public. No extra CRM2 role is imposed here.

Parameters

ParameterTypeRequiredDescription
providerStringYesCase-insensitive after trimming: quickbooks, xero, or microsoftbusinesscentral. Other names, including datasync, are rejected by the cloud facade.
retPresent valueNoFor Xero and Business Central, any non-null supplied value, including 0 or an empty string, selects a JSON URL response. Omit it for an HTTP redirect. QuickBooks returns JSON regardless.
api_serverHTTPS URLNoCallback host override, otherwise the current HTTP host. Xero and QuickBooks accept only https:// followed by a lowercase alphanumeric Fieldmotion subdomain and trailing slash; Business Central uses its broader Fieldmotion host pattern. Use the account’s configured API server.
reconnectLegacy UI valueNoThe Xero UI sends 1 when renewing consent. This authorization function does not branch on this flag; callback/session behavior controls reconnection.

Example request

$result = FM_api('Accounting_authorisation', ['provider'=>'xero', 'ret'=>'1']);

Example response

{
  "url": "https://login.xero.com/identity/connect/authorize?...",
  "redirect": "https://replace-with-your-host.fieldmotion.com/a/Xero_callback",
  "provider": "xero",
  "ok": 1
}

Database numeric values can be strings. Read the JSON error/warning fields as well as the HTTP status.

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: provider"}The provider is absent or outside the facade whitelist.
{"error":"Xero client info not configured"}Server OAuth credentials are missing for Xero.
{"error":"Microsoft Business Central client info not configured"}Server OAuth credentials are missing for Business Central.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • The facade appends provider and supplies ok:1 only when the returned array has no error or ok. Provider-specific fields remain intact; early provider validation errors have no provider field.
  • Xero is the facade’s public authorization exception and is reachable through the dispatcher’s public Xero GET flow. QuickBooks and Business Central require login. A signed-in request still follows normal session/CSRF handling.
  • Callbacks remain PluginQuickBooks_registerToken, Xero_callback and SyncMicrosoftBusinessCentral_callback. Provider application credentials must already be configured on the server.
  • Xero requests granular invoice/payment scopes. Renew consent without disconnecting or clearing links; its signed-in callback retains the linked organization. Authorization does not configure tax/account mappings or select a Business Central company.

Side effects

  • Stores the callback API server in the session. Xero and Business Central create a global oauth_logins state row; the provider callback later saves tokens/connection state.
  • Opening the returned URL starts external provider consent. The no-ret redirect paths exit before JSON normalization.

See it in Fieldmotion

CRM1

Open Settings → Finances and the QuickBooks or Xero integration. Filter the browser Network panel for this Accounting route; these screens send provider explicitly. Provider-specific setup remains on the original provider routes. Click Connect or renew Xero permissions; ret=1 returns a URL for the consent popup. Business Central has no CRM1 settings caller; its configuration UI is CRM2-only.

CRM2

Open Settings → Finances and the corresponding provider. The QuickBooks widget, Xero settings/background sync, and Business Central action wrapper call this facade with provider. Filter the browser Network panel for the endpoint name. Click Connect or renew Xero permissions; ret=1 returns a URL for the consent popup.

Related endpoints