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.
How to register an application
- Start by registering a public application.
- 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.
- 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/…|
- 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.
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
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