Start Free Trial   Support

Xero Advanced Settings

Establishing a Connection

Connecting to a Xero API

 The provider supports the following Xero APIs:

  • Accounting API: Set the Schema connection property to ACCOUNTING
  • Australian Payroll API: Set the Schema connection property to PAYROLLAUS
  • Files API: Set the Schema connection property to FILES
  • Fixed Assets API: Set the Schema connection property to ASSETS
  • Projects API: Set the Schema connection property to PROJECTS

Authenticating to Xero

By default the provider authenticates to Xero using OAUTH2. In addition, the provider supports the following legacy authentication modes. They are included for compatibility and should not be used for new integrations.

  • PUBLIC
  • PARTNER
  • PRIVATE

Custom Credentials

When to Use a Custom OAuth App

You need to create an app as shown in the following authentication guides. 

Desktop Authentication with a Custom OAuth App

Follow the steps below to authenticate with the credentials for a custom OAuth app.

Get and Refresh the OAuth Access Token

After setting the following, you are ready to connect:

  • OAuthClientId: Set this to the client Id assigned when you registered your app.
  • OAuthClientSecret: Set this to the client secret assigned when you registered your app.
  • CallbackURL: Set this to the redirect URI defined when you registered your app.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
  • XeroAppAuthentication: Set this to OAUTH2.

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

  1. Extracts the access token from the callback URL and authenticates requests.
  2. Obtains a new access token when it expires.
  3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Web Authentication with a Custom OAuth App

When connecting via a Web application, you need to register a custom OAuth app with Xero; 

Get an OAuth Access Token

Set the following connection properties to obtain the OAuthAccessToken:

  • OAuthClientId: Set this to the Client Id in your app settings.
  • OAuthClientSecret: Set this to the Client Secret in your app settings.
  • XeroAppAuthentication: Set this to OAUTH2.
  • Scope: You may set this to a space-separated list of Xero OAuth scopes. This is recommended if your application only uses one schema, since otherwise the provider will request all available scopes.

Refresh the OAuth Access Token

You can set InitiateOAuth to REFRESH to automatically refresh the OAuth access token when it expires.

Automatic Refresh

To refresh the token with InitiateOAuth, set the following on the first data connection:

  • OAuthAccessToken: Set this to the access token.
  • InitiateOAuth: Set this to REFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
  • OAuthSettingsLocation: Set this to the path where the provider will save the OAuth values, to be persisted across connections.
  • OAuthClientId: Set this to the Client Id in your app settings.
  • OAuthClientSecret: Set this to the Client Secret in your app settings.
  • OAuthRefreshToken: Set this to the refresh token.
  • XeroAppAuthentication: Set this to OAUTH2.

On subsequent data connections, set the following:

  • InitiateOAuth
  • OAuthSettingsLocation
  • XeroAppAuthentication

Creating a Custom OAuth App

The following sections show how to create a custom OAuth app for use in the Custom Credentials authentication flow.

Custom ApplicationGuidelines

Creating a custom app is required to use the default OAUTH2 authentication method.

You will need to configure a different redirect URI depending upon what product you want to use. The common redirect URIs for different products include:

  • Data Sync http://localhost:8019/src/oauthCallback.rst
  • API Server https://oauth.cdata.com/oauth/
  • Drivers and Connectors http://localhost:33333

Register an OAuth Application: Desktop

Follow the steps below to register a public application to obtain the OAuth client credentials:

  1. Log in to the Xero developer portal.
  2. Click My Apps -> Add Application.
  3. Enter a name for your application and the URL of your company. This information is displayed to users when they connect.
  4. Register the Redirect URI appropriate for the product you are using.

After you click Save, you are shown your OAuth Client ID and can create a new OAuth Client Secret.

Register an OAuth Application: Web

Follow the steps below to register a public application and obtain the OAuthClientId and OAuthClientSecret.

  1. Log in to the Xero developer portal.
  2. Click My Apps -> Add Application.
  3. Enter a name for your application and the URL of your company. This information is displayed to users when they connect.
  4. Set the Redirect URI to the full redirect or callback URL, where the user returns with the token that verifies that they have granted your app access.

After you click Save, you are shown your OAuth Client ID and can create a new OAuth Client Secret.

Register an OAuth Application: Headless Machines

 Follow the steps below to register a public application and obtain the OAuthClientId and OAuthClientSecret.

  1. Log in to the Xero developer portal.
  2. Click My Apps -> Add Application.
  3. Enter a name for your application and the URL of your company. This information is displayed to users when they connect.
  4. Register the Redirect URI appropriate for the product you are using.

After you click Save, you are shown your OAuth Client ID and can create a new OAuth Client Secret.

Connecting Through a Firewall or Proxy

HTTP Proxies

To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.

In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.

Other Proxies

Set the following properties:

  • To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
  • To tunnel the connection, set FirewallType to TUNNEL.
  • To authenticate, specify FirewallUser and FirewallPassword.
  • To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

Troubleshooting the Connection

To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.

  • Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
  • Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.