Skip to content
 

Developer

See all pages
Try Xero Free

Setup an Application

Xero supports three types of applications that can connect to the Xero API.

  • Public Applications can be registered by any user with a Xero login. These applications can have short term access to any organisation.
  • Partner Applications are like public applications, but are approved by Xero and have long term access to any organisation.
  • Private Applications have a permanent connection to a single organisation. This is useful when you are developing your own integration software for your organisation.

Public Applications

Public applications can be connected to any Xero organisation via the standard 3 legged OAuth process.

You’ll need to go to the My Applications > Add Application screen in the Xero Developer portal (https://api.xero.com) to add your application.

  • Web based applications can specify a call back domain to redirect users back to your application after authorising access to their Xero organisation. Non web based applications will be given a authorisation code to enter into your application to complete the authorization process. Further info on callback domains here.
  • By default public applications are granted access for 30 minutes. Server based applications can be upgraded to “partner status” where you can be given longer access to organisations without end users having to reauthorize access.

Here are a couple of notes about the authentication within Xero

  • Only signatures signed using HMAC-SHA1 will be accepted.
  • We use revision 1a of the OAuth protocol
  • Once users have validated a request token the request token is linked to a single user-> organisation pair, the access token cannot be used against alternative organisations or users.

Further details on the security requirements for public applications can be found on the Authentication page.

Partner Applications

Partner applications are public applications that have been upgraded and given longer access to organisations without end users having to reauthorize access.

There are additional security requirements in exchange for longer access.

  • You will sign messages using the RSA-SHA1 signing method. For this you’ll need to generate a public & private key pair and upload the public X509 certificate when applying to be upgraded.
  • We’d like all our API Partners to have a privacy policy, to make sure that you keep customers’ data safe. When you apply for an upgrade to partner status, you’ll need to enter the URL of your privacy policy. The Xero Privacy Policy might give you an idea of what we’re looking for.
  • You’ll connect to a different API server that requires client SSL certificates
  • We will also issue you with a client SSL certificate when calling the API Partner server.
  • Each access token will still last for 30 minutes, but they are renewable as per the OAuth Session 1.0 Draft 1 specification.

If you are developing an application that is installed on personal computers or mobile devices, but wish to have long term access to applications, we would recommend that you install a central server to handle the communication to the Xero API. We wouldn’t recommend embedding consumer secrets and keys, private certificates and other sensitive information into applications that are distributed to customers.

Further details on the security requirements for partner applications can be found on the Authentication page.

Please email network@xero.com to express your interest in upgrading your application to partner status.

Private Applications

Private apps are for use with one of your own Xero organisations.

  • Private applications use 2 legged OAuth and bypass the user authorization workflow in the standard OAuth process. Your access token is permanent but can be revoked inside the Xero application (via the Xero Network settings screen) or regenerated in the My Applications screen in the developer centre.
  • When using a private app all calls to the Xero API must be signed using your private key with the RSA-SHA1 signature method.
  • A X509 certificate containing your public key will need to be uploaded to Xero so that we can verify the source of the incoming request message.

Further details on the security requirements for private applications can be found on the Authentication page.

Generating Self-signed Certificates (X509)

Private and Partner application must sign messages using the OAuth RSA-SHA1 method. This requires that you create a public/private key-pair, and upload the public certificate to the Xero API server.

To get started with creating a public/private key-pair we recommend the use of OpenSSL (http://www.openssl.org).

Windows users

You can download OpenSSL for Windows here.
http://www.slproweb.com/products/Win32OpenSSL.html
To run the commands below, go to the OpenSSL32 directory on your PC, and the change to the /bin directory.

Mac users
OpenSSL comes shipped with Mac OS X version 10.6.2
See http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man1/openssl.1ssl.html for more info.

Using OpenSSL

The basics command line steps to generate a private and public key using OpenSSL are as follow

  1. openssl genrsa -out privatekey.pem 1024
  2. openssl req -newkey rsa:1024 -x509 -key privatekey.pem -out publickey.cer -days 365
  3. openssl pkcs12 -export -out public_privatekey.pfx -inkey privatekey.pem -in publickey.cer

Step1 – generates your private key
Step 2 – generates your public key which you use when registering your private application
Step 3 – exports your public and private key to a pfx file which can be used to sign your OAuth messages.

You’ll need to go to the My Applications > Add Application screen in the Xero Developer portal (https://api.xero.com) to add your application. Once you have added a private app you will be given a consumer key and consumer secret to use. The consumer key and consumer secret are also used as the access token and access secret.