XeroAPI OAuth Migration Strategy

We’ve put together some helpful strategies for exchanging your OAuth 1.0a access tokens for OAuth 2 tokens. Migrating means your customers won’t need to re-authorize access to your application.

Support for OAuth 1.0a will be deprecated in March 2021.

I recommend reading Adam Moore’s blog on Xero’s migration as a primer.

In this post I will illustrate how to swap OAuth 1.0a tokens for OAuth 2 tokens using a Ruby script with minimal dependencies. The code is available on Github with additional technical documentation.

If you prefer video format, checkout the youtube recording where I use the full Ruby script to migrate OAuth 1.0a tokens.

Token Migration Strategy

Having a solid migration strategy is essential to maintain your customer’s API connections and ensure critical accounting data flows are not interrupted.

There are two key steps to complete the OAuth 2 migration:

1. Change your code to pass xero-tenant-id to identify the organisation.
2. Migrate access tokens for each customer

Things to consider for your migration project:

• Will you run migration in bulk, batches or in-line?
• Are you storing & passing xero-tenant-id http header in all your API calls?
• Is your database prepared to store OAuth 2 token_sets in JWT format?
• Have you built OAuth 2 token refresh logic (ex. retry pattern)?

Tip 1: For large connection counts migrate users in batches

Do a small batch, observe traffic/logs for a while, and then another one until the whole user base is migrated over.

Tip 2: Refresh OAuth 1.0a token, and code new refresh logic

Refresh the OAuth 1.0a tokens you are swapping so they are valid when you hit the migration endpoint.

Unlike the OAuth 1.0a session_handle which is long-lived, the OAuth 2 refresh_token only lives for 60 days from issuance. You will need to add code that refreshes your OAuth 2 tokens at least once every 60 days to persist API connections.

Tip 3: Keep the old OAuth 1.0a token as a backup.

Don’t discard the OAuth 1.0a tokens right away. You can use your migration script to recover an OAuth 2 token easily before the full deprecation of OAuth1.0a in Xero. With the addition of scopes you will want to ensure all your existing API endpoints are covered with the new token’s permissions.

Tip 4: Leverage one of Xero’s supported SDK’s

Since OAuth 2 tokens are now one-to-many, instead of one-to-one we have a suite of Xero supported SDK’s built from our Open API specifications.

C# | Java | PHP | Ruby | Node | Python

For the rest of this post I will assume your application is successfully connected to Xero’s API using an OAuth 1.0a library to obtain/refresh tokens, and make valid API calls.

However, if you are trying to migrate in an environment that does not include an OAuth 1.0a library that handles the inclusion of the oauth_signature and other necessary headers there is additional technical documentation to see how that is done in the full ruby script.

https://github.com/XeroAPI/xero-ruby-token-migration-script

Setup OAuth 2 App credentials from existing Partner app

This will push your existing connection cap to be inherited by the new OAuth 2 app. Especially important for certified apps completing migration.

On your /myapps dashboard go to your Partner app to generate your new OAuth 2 credentials. Once you add the redirect URI, you will be able to view your new client_id and generate your client_secret that you will need in the POST to the migration endpoint.

Your Partner app will have an area to generate your OAuth 2 credentials

Migrating your OAuth 1.0a Token

Let’s build up our migration POST params for the OAuth 2 app we should have created on our /myapps dashboard.

You will need to decide what scopes are appropriate for your application https://developer.xero.com/documentation/oauth2/scopes

We can now format our request and receive back an OAuth 2 token_set.

• Assumes authorization_header is handled by an OAuth 1.0a library
• Add the POST body in json format
• Make the API call

puts response.body

Tada 🥳- Your OAuth 2.0 token_set

You’re now the proud owner of an OAuth 2 token_set!

Now we need to move the new token_set to our production environment and associate it with the user who initially authorized the XeroAPI connection for OAuth 1.0a.

If you were to head over to https://jwt.io/ and decode the “access_token” you can see some interesting info regarding your new connection.

{
  "nbf": 1591647531,
  "exp": 1591649331,
  "iss": "https://identity.xero.com",
  "aud": "https://identity.xero.com/resources",
  "client_id": "YOUR_OAUTH2_CLIENT_ID",
  "sub": "unique-id-of-whom-token-refers-to",
  "auth_time": 1591647531,
  "xero_userid": "my-xero-users-uuid",
  "jti": "8baaa748014dff96b7bfd97a9b59a0d3",
  "authentication_event_id": "uuid-relating-to-the-auth-event",
  "scope": [
    "offline_access",
    "accounting.transactions",
    "accounting.setting"
  ]
}

You will also see that in the full token_set there is a new value returned:

“xero_tenant_id”: “xxx-xxx-xxx-xxx”

This is the largest difference for developers to adapt to between the two authorization gateways. There is now the potential for users to authenticate multiple organisations under the same “access_token”.

Every API call will now need to have the xero-tenant-id specified in the header. Fortunately we have a suite of Xero supported SDK’s that make this easy. They also include authorization flows to generate OAuth 2 token_sets for new users in your application.

How I feel right now

Let this celebratory parting gif properly express our gratitude for your investment into XeroAPI ecosystem and represent our excitement for the future of building amazing tools and businesses with accounting data.

If you still have concerns about your XeroAPI token migration strategy, drop us a line at api@xero.com — we’ll do our best to provide suggestions to mitigate risk.

If you enjoyed this article or have ideas for more technical content about the XeroAPI find me @nomadic_knight ️️