caret

Postman - OAuth 2.0

Postman and Xero

Xero uses a standard OAuth 2.0 system. Postman can be useful to test your API calls without having to code anything. We've created a Postman collection that makes authentication easy. Postman is a REST client that provides an intuitive user interface to send requests, save responses, add tests, and create workflows.

Get started by heading to our Xero-Postman-OAuth2 Github repo or just use the "Run in Postman" button below and follow the steps:

Steps to get up and running

  1. Import the Xero OAuth 2.0 collection and Xero environment into Postman
    2.

    Click the button below and select the Desktop version of Postman (Chrome extension doesn't support environment variables). This will also install the Collection and Environment we'll be using.

    Run in Postman
  2. Create an OAuth2 app at https://developer.xero.com/myapps
    3.

    Go to the Xero developer portal and create an OAuth2 app.

    If you haven't already signed up for a xero account you can do so here.

    Use the following values:

    • App Name - your choice, but can't contain the word 'Xero'
    • Company or application URL - this needs to be an https address, but isn't used
    • OAuth 2.0 redirect URI - also needs to be https but won’t be used in postman
    App details

    Then:

    1. Click Create App
    2. Click Generate a secret
    3. Keep the page open
    created app details
  3. Add your first set of environment variables in Postman
    4.

    Copy the Client id, Client secret and OAuth 2.0 redirect URI from the My Apps screen into the environment variables in Postman. To add these details to the Environment, make sure you have the OAuth 2.0 Environment selected, click the eye button, then edit.

    environment screen in Postman
  4. Add the scopes for the endpoints you will be accessing
    5.

    Our Developer Center lists the available scopes here. For getting started you will need at least:

    offline_access accounting.transactions

    In addition, to make further test calls we would also suggest adding:

    openid profile email accounting.contacts accounting.settings

    Add the scopes required to the scopes environment variable.

    environment screen in Postman with scopes field completed
  5. Generate your access token
    6.

    1. Double-click on the GET Get Started request under the Xero OAuth 2.0 Collection
    2. Select the Authorization tab
    3. Click Get New Access Token
      4. getting a new access token
    4. Add the Variable names surronded by {{}} from your Environment into the fields, as shown in the screenshot below
    5. Add https://login.xero.com/identity/connect/authorize to the Auth URL field
    6. Add https://identity.xero.com/connect/token to the Access Token Field
    7. Click Request Token
      8. fields on Get New Access Token Dialog box

    At this stage you will be prompted to log in to Xero.

    Xero login screen

    If you've included the openid profile email scopes, you'll be asked to access your basic profile information.

    Xero user account information screen

    You'll then be taken through to the Organisation Select window. Select the Organisation you want to connect to. If you want to connect to more than one Organisation, you can repeat the steps above and select another Organisation.

    Xero organisation data permission screen

    Once complete you'll be passed back to Postman.

  6. Set your Access and Refresh Tokens
    7.

    We now have the last remaining tokens needed to access the Xero API. These need to be set to the Environment Variables, to do this:

    1. Highlight the Access Token
    2. Right-click on it
    3. Select Set: OAuth 2.0 > access_token

    Follow the same process for the Refresh Token.

    populating the tokens using the context menu
  7. Find out which tenants (organisations) we are connected to
    8.

    1. Double-click on the GET Connections request
    2. Click Send
    3. Like we did for the Access and Refresh Tokens, highlight the tenantId from the response, right click and select Set > OAuth 2.0 > xero-tenant-id
    connections endpoint in postman

    Congrats! You're now authenticated and can start making API calls. Your access token will last for 12mins, after which time you'll need to refresh the token.

  8. Make your first API call!
    9.

    1. Double-click to load the GET Invoices request
    2. Ensure No Auth is set on the Authorization tab
    3. Click Send

  9. Refreshing the token
    10.

    1. Double-click to load the POST Refresh token request
    2. Ensure No Auth is set on the Authorization tab
    3. Click Send

    Notes:

    • We use the built in OAuth 2.0 support to get the token, however we then set this as an environment variable. So we don't need to use this support when making the normal API calls.
    • The supplied Invoices GET call includes a script to refresh the token. This is primarily to make the process easier whilst using Postman. In production we would recommend only refrehsing the token when required.