OAuth Issues

Token Rejected (token_rejected)

There are a number of conditions where this can be seen:

The access token has not been authorized

oauth_problem=token_rejected&oauth_problem_advice=The access token has not been authorized, or has been revoked by the user
There are a number of scenarios where this can occur:
  1. A user has revoked access: a standard or financial user with access to the organisation in Xero can revoke authorisation from the Add-ons page under Settings > General Settings in Xero.
  2. User permissions changed: if the user who has authorized the connection between the API application and the Xero organisation is removed from accessing the organisation in Xero, or their role changes so that they are no longer a standard or financial adviser user, then the access token will no longer be authorized.
  3. A second authentication has taken place: an access token is a unique pairing of the API application and the organisation in Xero. If, under a separate login/instance of your application, a user attempts to authenticate a connection to the same organisation in Xero, this will replace the previous access token, generating the above error condition.
Resolution: There is no technical solution to the above conditions - you should ensure your application can handle a situation where the authentication session has been lost gracefully, and prompt the user to re-authenticate. If this is happening because of one of the above scenarios on a regular basis, you might need to examine more closely the reasons why, and educate users accordingly.

Does not match an expected access token

oauth_problem=token_rejected&oauth_problem_advice=Token THISISANCCESSTOKEN does not match an expected REQUEST token
This error will occur in a partner API application when an attempt to renew the access token is made, but the Xero API is expecting the access token to be swapped out that is not the same as the one presented, so somehow your application may have lost track of what the most recently expired token is eg:
  1. Get new token access token 1
  2. Swap for access token 2, but somehow your application does not save access token 2
  3. Attempt to renew token with access token 1, but we now expect access token 2, so we throw the above error
Resolution: The key thing is to understand how your application may lose track of a given access token - potentially a race condition exists where an access token renewal is made in parallel, or the current token is not being saved to a persistent storage object.

This error will also occur if the session handle is not used in the access token renewal process.

Resolution: Store the session handle and use it when renewing the access token.

The organisation for this access token is not valid

oauth_problem=token_rejected&oauth_problem_advice=The organisation for this access token is not valid
This occurs typically when a Demo company is being used to test/develop an application. Demo companies reset every 28 days, and in doing so all existing data including access tokens and private applications are disabled. Other possibilities are if the organisation has been suspended or disabled for billing issues or the subscription has been cancelled.

Resolution: Create a new connection with the new demo company, or in the case of issues not related to demo companies, contact the Xero subscriber for more information.

Token has not been provided

oauth_problem=token_rejected&oauth_problem_advice=Token has not been provided
If for some reason, the access_token value is not being received by the API. The value may be empty or the access_token parameter may not be passed in at all.

Resolution: Validate you are storing and handling access tokens correctly. If you are using a wrapper library or code sample, try to debug the access_token values as they are being sent to the API.

Token Expired (token_expired)

The access token has expired

oauth_problem=token_expired&oauth_problem_advice=The access token has expired.

This is a normal response in both Public and Partner API application types where access tokens last only 30 minutes.

Resolution: For Public applications, authentication sessions last 30 minutes. The user will need to re-authenticate the connection, and your application will then use a new access token. For Partner API applications, the session lasts longer, and a new access token can be requested via the API.

Nonce Used (nonce_used)

The nonce value "XXX" has already been used

oauth_problem=nonce_used&oauth_problem_advice=The nonce value "XXX" has already been used
This error occurs when you make an OAuth request using a nonce value that has been already submitted in a previous request. The Xero API records the last 20 nonce values submitted for each application.

Resolution: If you are using one of the code samples, the nonce value should be randomly generated and unique to each request. It may be that the your application is resubmitting the same OAuth request a second time (a double hit) somehow. Once you have ensured your nonce value is being randomly generated, you could use a HTTP proxy such as Fiddler or Charles to see what is being sent to the server.

Timestamp Refused (timestamp_refused)

This error can occur when the OAuth timestamp you present to the Xero API is either 5mins slower or 5mins faster than the actual time. This time is not timezone dependent - the timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. It should therefore be correct unless the clock on your server is out of sync with the actual time by 5mins or more.

Too old

oauth_problem=timestamp_refused&oauth_problem_advice=The timestamp is too old, it must be at most 300 seconds before the server's

Too new

oauth_problem=timestamp_refused&oauth_problem_advice=The timestamp is too far in the future, it must be at most 300 seconds after the server's current date and time

Resolution: You should ensure that your server clock is up to date. If you are unsure if the timestamp generated by your server is correct, you can check it at UnixTimeStamp.com.

Signature Method Rejected (signature_method_rejected)

No certificates have been registered for the consumer

oauth_problem=signature_method_rejected&oauth_problem_advice=No certificates have been registered for the consumer
This can be encountered if the public private key pair X509 certificate used for Private and Partner applications has an expiry date that has passed.

Resolution: You will need to upload a new certificate. Read our guide on adding an application on the Xero Developer Centre site to learn more about creating a new X509 public key certificate. Once created, the public key will need to be uploaded to your application: go to My Applications in the Xero Developer Centre, and edit the application in question (you should see a message that the certificate no longer exists if the previous one has expired).
Note that the new private key needs to also replace the old private key referenced within your application. If you do not do this, you will see a "signature invalid" OAuth message.

Public applications must use the HMAC-SHA1 signature method

oauth_problem=signature_method_rejected&oauth_problem_advice=Public applications must use the HMAC-SHA1 signature method
This can be encountered if the consumer key used to identify the API application in use is not a public API application.

Resolution: Ensure that you are using a consumer key of a Public API application. You can check this at api.xero.com.

Signature Invalid (signature_invalid)

This can be quite generic reason for a number of signature generation errors. The best tip here is using an up to date version of one of our recommended code samples as they take care of signature generation.

Failed to validate signature

oauth_problem=signature_invalid&oauth_problem_advice=Failed to validate signature
Some possible causes:
  1. The public-private application certificate keypair used to sign requests does not match the public key uploaded to your application in the Xero Developer Centre
  2. The application consumer key does not match the application certificate keypair
  3. Not all expected elements are being used to generate the signature.
Resolution: No easy way to advise on the specific issues here. Again we recommend using a code sample if possible, but if you are still stuck having gone through the possible causes above, ask a question in our developer community. A GET request requires less parts of the request to be signed - check if you can make a GET request before moving on to PUT/POST as this will help isolate the cause.

Permission Denied (permission_denied)

These errors are triggered when the OAuth layer believes you do not have permissions to make a given request, though it has been correctly signed. This will generally occur where there are misconfigurations in your setup.

Consumer key was not recognised

oauth_problem=permission_denied&oauth_problem_advice=Consumer key was not recognised
This error will be returned when using the Partner API application type with an invalid consumer key to identify your application. The most likely reason would be a mix up between the consumer key and consumer secret.

Resolution: Check the settings for your consumer key are correct - you can view the consumer key and secret values in the developer centre under 'My Applications'.

Consumer key does not correspond to a registered partner application

oauth_problem=permission_denied&oauth_problem_advice=Consumer key does not correspond to a registered partner application
This error will be returned when using the Partner API application type with a consumer key which belongs to an API application that is not a partner API application. A possible cause would be continuing to use the consumer key of a public application which was upgraded to a partner API application (which creates a new partner API application with the same name, and new consumer key).

Resolution: Check the settings for your consumer key are correct and correspond to that of a partner API application - you can view the consumer key and secret values in the developer centre, and also confirm the application type under 'My Applications'.

Consumer key unknown (consumer_key_unknown)

The consumer key, which identifies a connecting application to the API, cannot be identified. This is most likely a configuration issue - not supplying the correct value, but there may also be instances in custom OAuth integrations where the value is set correctly, but is not being transmitted in an expected manner.

Consumer key was not recognised

oauth_problem=consumer_key_unknown&oauth_problem_advice=Consumer key was not recognised
This error will be returned when a consumer key value, does not match the consumer key value of a registered application.

Resolution: Check the settings for your consumer key are correct - you can view the consumer key and secret values in the developer centre under 'My Applications'.

Unknown Errors (xero_unknown_error)

Nobody likes an unknown error, but there can be an occasional one:

could not generate a access token

oauth_problem=xero_unknown_error&oauth_problem_advice=could not generate a access token
This is generally a temporary situation where an access token cannot be generated due an internal issue.

Resolution: Attempting a retry should be successful.