Partner Applications – certificates explained

Xero API Partner Applications can be authorized to provide long term access to multiple Xero accounts.
Due to the extended nature of this access, Xero have additional security requirements in place around certificates used to communicate with the Partner API.

Application Certificate
Each developer must generate a self-signed application certificate. The public cert part of this is uploaded as part of the application settings when creating or editing a partner application in the Xero Developer Centre. This certificate is used to sign messages during the OAuth process within your application.

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. 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.

In Summary
To use the Xero Partner API, you need two separate certificates:

1. Application certificate: used to sign OAuth messages, generally broken into two parts: a private key and public cert
2. Xero Entrust certificate: used to secure the client which connects to the API, and can be one single cert or a private key and public cert, depending on your application code/environment.

Using OpenSSL to split the Xero Entrust certificate
The command line steps to split the .p12 file into separate private key and public cert (if applicable)

1. openssl pkcs12 -in entrust-client.p12 -clcerts -nokeys -out entrust-cert.pem
2. openssl pkcs12 -in entrust-client.p12 -nocerts -out entrust-private.pem <- you will be prompted to enter a password
3. 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)

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