Frequently asked questions

Get help with common queries

 

OAuth 2.0*

Can I have more than three redirect URIs for my app?*

If your scenario requires more than three redirect URIs (e.g. users need to be redirected back to a number of different subdomains) then you can create a central redirect URI and use the state parameter to pass the values your app needs to produce the desired user experience.

  • Create a central redirect UI for your app to complete the authorization step. Send application specific parameters (e.g. the subdomain) in the state parameter. Take care to also still guard against CSRF.

  • When the user is redirected back to your central redirect URI the state parameter is sent back to your app.

  • Your app can then use the value in the state parameter to determine which URL to send the user to. Make sure you validate for CSRF protection.

Note: This approach could be compromised by the open redirector threat described in RFC 6819. Be careful to protect these parameters by encrypting the state or verifying them by some other means.

Can I use a wildcard in my redirect URI?*

The OAuth 2.0 spec (section 3.1.2 of RFC 6749) requires that a redirection URI must be an absolute URI. The use of wildcards in redirect URI is not supported.

How should I handle callback failure?*

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 connected the second time. They can continue to click through as normal to be redirected back to your app with a new code.

Is there an equivalent of two-legged private apps in OAuth 2.0?*

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.

What do I do if a token refresh fails?*

If you don't receive a response from a token refresh you can retry using your existing refresh token for up to 30 minutes. If you can’t refresh your access token in that time 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.

What is the expiration for a refresh token?*

Unused refresh tokens expire after 60 days. If you don’t refresh your access token within 60 days the user will need to reauthorise your app.

When you perform a token refresh, you should replace your existing refresh token with the new one returned in the response. If, for whatever reason, you don't receive the response you can retry refreshing your existing refresh token for a grace period of 30 minutes.

What is the expiration for an access token?*

30 minutes.

When is OAuth 1.0a being deprecated?*

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

  • 2nd December 2019: Developers could no longer create new OAuth 1.0a apps

  • Mid-December 2019: A migration endpoint was released allowing partner apps to seamlessly migrate existing connections to OAuth 2.0

  • December 2020: All app partners and accounting and bookkeeping partners expected to be migrated.

  • March 2021: OAuth 1.0a will no longer be supported for any integrations

Will OAuth 2.0 support desktop/mobile/single-page apps that can’t keep a client secret confidential?*

Xero supports the Proof Key for Code Exchange (PKCE) extension to the authorization code flow. This allows native apps to securely connect to our API without needing to store a client secret. Single page apps are not currently supported.