Authentication with the Xero API
OAuth Protocol
The Xero API uses the OAuth Protocol to authenticate 3rd Party applications with the Xero API. This protocol helps applications get authenticated against Xero organisations, without users needing to divulge their passwords outside of Xero. The Xero API uses version 1.0a of the OAuth protocol.
For information about the OAuth protocol the first port of call should be the OAuth protocol’s web site. Within this site there are a number of great resources to get you started.
We have developed 3 flavours of authorization to connect to connect to the Xero API: Public, Private and Partner. If you are unsure what type of authorisation you need, see the API Overview page for a description of each.
Any developer can register a public application to access Xero. Once you have registered a public application, you can start to use the consumer key and secret immediately.
- Only messages signed using HMAC-SHA1 will be accepted.
- Public applications use the 3-legged authorization process. A user will need to authorize your application against each organisation that you want access to. Your application can have access to many organisations at once by going through the authorization process for each organisation
- The access token will only last for 30 minutes. If you want longer access to the organisation, you will need the user to re-authorized your application.
The URL’s to authorize your 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 |
| Connect to the Xero API: |
https://api.xero.com/api.xro/2.0/... |
Read our guide on setting up a public application
Note: When getting a request token and specifying the callback URL, the callback URL should be no more than 250 characters long.
Private applications use 2 legged OAuth and bypass the user authorization workflow in the standard OAuth process as the consumer key and consumer secret are also used as the access token and access secret. For full details read our guide on setting up a private application.
- Only messages signed using RSA-SHA1 will be accepted
- Private applications used the 2-legged authorization process. Once you register your application on the API website, you do not need to go through the user authorization process.
- When you register your application, you will select the organisation that is authorized to your application. This cannot be changed afterwards, although you can register another private application if you have multiple organisations.
- When you’ve registered your private application, the generated consumer key and secret are also used as the access key and secret.
A public application can be upgraded to partner status. This will give you long term access to organisations without needing a user to re-authorize your application every 30 minutes. Learn more about becoming an Xero Network partner
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. The access tokens can be renewed without further user authorization.
- Only messages signed using RSA-SHA1 will be accepted. When requesting an upgrade to partner status, you will need to upload a public certificate that you’ll use to sign the message.
- Partner applications use the 3-legged authorization process to authorize your application against organisations.
- We will issue you with a private/public certificate for you to use as a client SSL certificate. We have a separate API server for partner applications that requires client SSL certificates.
- Each access token lasts for 30 minutes, but an access token can be renewed, before or after it has expired, for another access token – which is usable for another 30 minutes. This process of token renewal can occur indefinitely, while the partner application is in active use, and API calls to the user account are made regularly (within 90 days of previous call).
- To help track the expiry time of the access token and session, additional response parameters will be returned from the /OAuth/AccessToken method: oauth_session_handle; oauth_expires_in; oauth_authorization_expires_in
Note: The client SSL certificate that you will use to connect to the api-partner.network.xero.com website is signed by EnTrust. Some server environments require that the public certificate from the signing authority is added to the servers local certificate store. If you are having problems using the client SSL certificates, please download the EnTrust public certificates and install them on your workstation or server.
For Partner applications, the URL’s to authorize your 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/... |
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 |
External Links
Also there’s a number of other useful resources
-
OAuth Core 1.0 Revision A
- Google OAuth Playground
- Yahoo! OAuth Quick start guide
- Beginner’s Guide to OAuth
- OAuth Wiki
- OAuth Session 1.0 Draft 1 Specification
We hope that you won’t be writing you own OAuth authorization library for your application. There are a number of existing libraries for all the common development platforms that you can use:
OAuth Requests may result in failures which will be one of the following:
- consumer_key_refused
- consumer_key_rejected
- consumer_key_unknown
- nonce_used
- parameter_absent
- parameter_rejected
- permission_denied
- permission_unknown
- signature_invalid
- signature_method_rejected
- timestamp_refused
- token_expired
- token_rejected
- token_revoked
- token_used
- version_rejected
for a complete reference of what these mean please see this page http://oauth.pbworks.com/ProblemReporting