Frequently asked questions

Here's what to expect with the move to OAuth 2.0:

• 2nd December 2019: Developers will no longer be able to create new OAuth 1.0a apps
• Mid-December 2019: A migration endpoint will be available allowing partner apps to seamlessly migrate existing connections to OAuth 2.0
• December 2020: OAuth 1.0a will no longer be supported for any integrations

We recommend creating OAuth 2.0 apps for all new integrations.

No, all users will follow the same OAuth 2.0 code flow. Once you have an access token and refresh token you can refresh indefinitely or until the token is revoked by the user.

30 minutes.

Refresh tokens expire once they’re used or after 30 days. If you don’t refresh your access token within 30 days the user will need to reauthorize your app.

If you can’t refresh your access token you’ll need to send the user through the authorization flow again to get a code that can be exchanged for a new access and refresh token.

If the callback fails for any reason you will need to send the user through the auth flow again. If the user got as far as connecting their org the first time, it will show as already connectected the second time. They can continue to click through as normal to be redirected back to your app with a new code.

At the moment, we require that your app can keep a client secret confidential. We are currently evaluating the PKCE extension to better support SPAs and mobile apps.

We encourage anyone building new apps to use OAuth 2.0 but we will continue to certify OAuth 1.0a integrations until the end of March 2020. Please be aware that if you choose to launch with OAuth 1.0a you will be required to migrate it to OAuth 2.0 before December 2020

There’s no need for re-certification. Partners will be able to generate an OAuth 2.0 client id and secret for their existing partner app, which will give them no connection limit, as well as any special scopes they currently have. More details on this soon.

The concept of "app types" will be going away with OAuth 2.0. All apps will use the same authentication flow. Connection limits limits will be the main difference between certified (i.e. partner) and uncertified (i.e. public/private) apps. New apps will be able to connect with up to 25 organisations before they need to get certified to have the connection limit removed. Please see the OAuth 2.0 docs for more details.

All OAuth 2.0 apps will be able to maintain an offline connection (like partner apps can currently).

If you have a custom integration with multiple organisations (e.g an accounting practice or franchise) then get in touch with us at api@xero.com, tell us more about your use case and we can adjust your connection limit accordingly.

We have a migration endpoint that allows partner apps to swap existing OAuth 1.0a tokens for new OAuth 2.0 tokens. Users won't have to reauthorize your app.

We won’t be offering a migration flow for public or private apps. If you have clients using those apps then you will need to create a new OAuth 2.0 app and ask them to re-authorise.

We have released 5 new SDKs (.NET, NodeJS, PHP, Java, Ruby) all built from the ground up with OAuth 2.0. We'll be adding Python by March 2020. We don't have any plans to add OAuth 2.0 support to the OAuth 1.0a SDKs.

The first step is to sign up for a free Xero account. Once you have done that, you have two options as to how you can begin development without incurring any cost:

• Use the demo company (recommended)
• Start a trial or paid Xero organisation subscription

Check out our Development Accounts guide for more details.

There are limits to the number of API calls that your application can make against a particular Xero organisation.

• Minute Limit: 60 calls in a rolling 60 second window
• Daily Limit: 5000 calls in a rolling 24 hour window

If you exceed either rate limit you will receive an HTTP 429 (too many requests) response. For a full list of API limits, pleae check our API Limits page

You can do more than one thing in a single request: For example, you can create more than one Invoice in a single PUT or POST Invoices API call. While there is no upper limit in the number of nodes that can be sent at one time, a ceiling of about 50 nodes per request is practical - this will ensure a request does not exceed the maximum size of 3.5MB. You should also review our notes on summarizing validation errors.

If you are hitting rate limits because you retrieve a large amount of data from Xero there are a couple of features you should be taking advantage of:

• You can use pagination to retrieve line item details for 100 items (e.g. Invoices) at a time. Endpoints on the Accounting API that currently support pagination are invoices, contacts, bank transactions and manual journals. All major endpoints on the Payroll, Files and Assets APIs also support paging.
• Use the If-Modified-Since header to retrieve only what's changed since your previous request

At Xero, we take the responsibility of managing our community’s data privacy and security seriously. As part of the work Xero has been doing with the Australian Tax Office and other industry players, we have developed a set of agreed security standards to be applied globally to our ecosystem. These come into effect for new app partners certified after 1 January 2020 and existing app partners have until 30 June 2020 to comply. We’re still working through all the details of our new process, but wanted to share this information with you early, so you can start to understand what these changes mean for your app.

In preparation to meet these new requirements, Xero will be updating our security requirements for our app and developer partners, as well as Xero’s App and Developer Partner Terms of Agreement.

All app partners will need to undertake a security assessment which will be reviewed by Xero’s security team. App partners who reach 1000 or more connections will be required to undertake an advanced security assessment which will also be reviewed by Xero’s security team. App partners will not be certified or listed in Xero’s app marketplace without passing these assessments. App partners will need to undertake and pass the security assessment on an annual basis.

We’ll keep our app partners updated via developer.xero.com, our twitter account and our developer emails.

• All app partners who wish to be certified and listed in the Xero app marketplace
• New app partners need to comply from 1 January 2020
• Existing app partners have until 30 June 2020 to comply

• An annual self assessment against the standard
• These new requirements will include, but are not limited to, API risk rating, authentication, certification, personnel security, encryption and audit logging
• 2SA will be the minimum level of account authentication but this will be provided already if your app connects with Sign in with Xero

We’re still working through the details of the process, but we’ll contact you when you need to undertake the security assessment and let you know the outcome of that assessment.

The security assessment will need to be undertaken annually.

https://www.absia.asn.au/industry-standards/addon-security-standard/