Partner Applications


Overview

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

  • Approved applicants will be issued with a Xero Entrust Client SSL certificate.
  • Partner applications use a different base url to access the Xero API. See the technical details below.
  • Partner applications use the same 3-legged authorization process as public applications, but the 30-minute access tokens can be renewed as per the OAuth Session 1 Draft 1.0 specification. 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

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-partner.network.xero.com/oauth/RequestToken
Redirect a user: https://api.xero.com/oauth/Authorize
Swap a Request Token for an Access Token: https://api-partner.network.xero.com/oauth/AccessToken
Swap an expired access token for a new one: https://api-partner.network.xero.com/oauth/AccessToken
Connect to the Xero API: https://api-partner.network.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.

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=31536000 Number of seconds before the session expires

The 30-minute access tokens can be renewed as per the OAuth Session 1 Draft 1.0 specification


Certificates

Xero Entrust Certificate

When the API team have reviewed and enabled your new partner application, we will issue you with a download link for a client SSL certificate, the Xero Entrust cert. The Xero Entrust cert download instructions are also available here. This is separate to the application certificate, and is used to identify the connection between your server and the Xero Partner API. This is not part of the OAuth signing process, but incorporated in your code’s method of connecting to the partner API.

Using OpenSSL to split the Xero Entrust certificate

The command line steps to split the .p12 file into separate private key and public cert (not applicable for IIS users)

openssl pkcs12 -in entrust-client.p12 -clcerts -nokeys -out entrust-cert.pem
## You will be prompted to enter the password that you used when creating the p12 file.
openssl pkcs12 -in entrust-client.p12 -nocerts -out entrust-private.pem 
## You will be prompted to enter the password that you used when creating the p12 file.
## You will be prompted to enter a new PEM pass phrase to be used with the private key

openssl rsa -in entrust-private.pem -out entrust-private-nopass.pem
## Last step removes the password that you added to the private key when it was exported 

Using partner applications with IIS

IIS Users will need to install both the self signed and Xero Entrust Certificate in the certificate store. Learn more

Xero Entrust Certificate renewal

The Xero API team keeps a record of Entrust certificates and their renewal dates.

  • We will contact you with instructions on how to download a new certificate at least a week prior to the certificate expiry date
  • The new certificate can be installed at any time before or after the current one expires – we recommend doing so a couple of days before
  • If there is an issue with the installation of the new Entrust cert, you will see a 403 API response – just reply back to the email if you need assistance from us
  • It is important to note that your self-created application certificate also has an expiry date, and generally expires before the Entrust cert – you can check the date from the application details page at api.xero.com