Partner Applications


Overview

Partner applications are public applications that have been upgraded to support long term access tokens.

  • Partner applications use the same 3-legged authorization process as public applications, but the 30-minute access tokens can be renewed. Access tokens can be renewed without further user authorization. This process of token renewal can occur indefinitely, while the partner application is in active use
  • Partner applications also use a different signature method to public apps. You need to sign your requests using the RSA-SHA1 method. More details are provided below.

Connecting and disconnecting an application

The process for an end user to authorise a partner application is identical to a public application.

Since your application will have long term access to an organisation, an end user may want to revoke access to an application. This can be done inside the Xero application (via the Add-ons settings screen (Settings > General Settings > Add-ons). Once an application has been revoked you need to follow the standard initial connection process ie. get a request token etc again.


Technical Details

How to register an application

  1. Start by registering a public application.
  2. Register your interest in becoming a partner and to apply to have your application upgraded to a partner application. Approved developers will be sent further details about how to complete this process.
  3. Once your application has been upgraded you have to upload your Xero public key. See signing requests below

Note: The name you select for your integration will be visible to end users. Check out our guide on branding your integration for more details.

URLs for authorising and using the Xero API

Xero follows the OAuth v1.0a spec. The URL’s to authorize your partner application are :

Get an Unauthorised Request Token: https://api.xero.com/oauth/RequestToken
Redirect a user: https://api.xero.com/oauth/Authorize
Swap a Request Token for an Access Token: https://api.xero.com/oauth/AccessToken
Swap an expired access token for a new one: https://api.xero.com/oauth/AccessToken
Connect to the Xero API: https://api.xero.com/api.xro/2.0/...

Callback URL

  • When getting a request token and specifying the callback URL, the callback URL should be no more than 250 characters long.
  • The callback url must be within the domain specified when registering your app. Learn more
  • Up to 3 callback domains are supported. When specifying more than 1 callback domain, separate each domain with a comma
  • If a callback url is not specified then the user will be given an authorisation code to enter into your application. The authorisation code is a fallback method, and should only be used if it is not technically possible to use the callback.

Signing requests

Only messages signed using RSA-SHA1 will be accepted. When requesting an upgrade to partner status, you will need to upload a self generated public certificate. To do this you need to generate a public/private key pair.

Refreshing access tokens

Each time that a Partner application calls the /OAuth/AccessToken method, the server will return a number of parameters in addition to the usual access token and secret:

oauth_token=ZWFHNMIWNZBMZJI1NDQ4ZJK0ZDGYMZ Access Token Key
oauth_token_secret=4MC3JQZHNG6DTKIKUITLNCYVFT61F7 Access Token Secret
oauth_expires_in=1800 Number of seconds before the access token expires
oauth_session_handle=ODJHMGEZNGVKMGM1NDA1NZG3ZWIWNJ Session Handle used to renew the access token
oauth_authorization_expires_in=315360000 Number of seconds before the session expires

FAQ: Refreshing access tokens

What do I need to store in order to refresh an access_token? You will need the access_token, access_token_secret and session_handle in order to refresh your existing access token for a new access token.

How long is an access_token valid for? An access_token is valid for 30 minutes.

What happens when my access_token expires? You can use your expired access_token (along with the session_handle and the access_token_secret associated with the access_token) to exchange the expired access_token, for a new access_token. The new access_token is valid for 30 minutes.

What endpoint do I use to exchange my access_token? /OAuth/AccessToken

I received an OAuth error, what does it mean? We have documented the common OAuth here.

I refreshed the access_token, but I'm getting an error: "Token [YOUR ACCESS TOKEN] does not match an expected REQUEST token" Something went wrong during your access_token refresh request. Most likely, you did not successfully store the new access_token. We suggest you immediately save the new access_token to your database / token store. More details on this error are available here, under 'Does not match an expected access token'.

I have an expired access_token, but I can not refresh it? You can ONLY refresh the most recent access_token. Upon generating a new access_token, all existing access_tokens are marked invalid. If you do not store the new access_token, you will no longer be able to refresh the access_token. You will need to request the user to re-autheticate with the Xero API in order to generate a new session_handle, access_token and access_token_secret.

I have an expired access_token, it will not refresh, can developer support help me? No, we can not manually modify access_tokens. You must request the organsation to re-authenticate your application with Xero API.

This process sounds hard, can you help me implement it? Never fear, the SDK's are here. There are SDK's for most languages that support the Partner App and the access_token refresh procedure. C#, PHP, Ruby, Python, Node, Java and you can search github for more.