Xero Node.js SDK

Once you have stored a TokenSet in your datastore, you can refresh it when it expires. There are two primary patterns for refreshing tokens:

1. Using a fully initialized client

Use this if you have already called client.initialize() and client.setTokenSet(tokenSet). This leverages the underlying openid-client library.

2. Refreshing without full initialization

If you have a valid refresh token (less than 60 days old) but don't want to perform a full initialization, you can use refreshWithRefreshToken by passing the client credentials and the refresh token directly.

// Pattern 1: Using initialized client
import { XeroClient } from 'xero-node';
const xero = new XeroClient({ /* config */ });
await xero.initialize();
const tokenSet = getTokenSetFromDatabase(userId);
await xero.setTokenSet(tokenSet);

if(tokenSet.expired()){
  const validTokenSet = await xero.refreshToken();
  // save the new tokenset
}

// Pattern 2: Using refreshWithRefreshToken
import { XeroClient } from 'xero-node';
const tokenSet = getTokenSetFromDatabase(userId);

if(tokenSet.expired()){
  const xero = new XeroClient();
  const validTokenSet = await xero.refreshWithRefreshToken(client_id, client_secret, tokenSet.refresh_token);
  // save the new tokenset
}

This example demonstrates the workflow for accessing the Accounting API: initializing the client, setting the token, updating tenants to find the active tenant ID, and performing CRUD operations on Invoices and History Records.

Note: When creating invoices, use the Invoice.TypeEnum and Invoice.StatusEnum for type safety.

import { XeroClient, HistoryRecords, Invoice } from 'xero-node';

const xero = new XeroClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUris: [`http://localhost:${port}/callback`],
  scopes: 'openid profile email accounting.settings accounting.transactions offline_access'.split(" ")
});

await xero.initialize();
const tokenSet = getTokenSetFromDatabase(userId);
await xero.setTokenSet(tokenSet);

if(tokenSet.expired()){
  const validTokenSet = await xero.refreshToken();
}

await xero.updateTenants();
const activeTenantId = xero.tenants[0].tenantId;

// GET all Accounts
const getAccountsResponse = await xero.accountingApi.getAccounts(activeTenantId);
const accountId = getAccountsResponse.body.accounts[0].accountID;

// CREATE an Invoice
const invoices = {
  invoices: [
    {
      type: Invoice.TypeEnum.ACCREC,
      contact: { contactID: contactId },
      lineItems: [
        {
          description: "Acme Tires",
          quantity: 2.0,
          unitAmount: 20.0,
          accountCode: "500",
          taxType: "NONE",
          lineAmount: 40.0
        }
      ],
      date: "2019-03-11",
      dueDate: "2018-12-10",
      reference: "Website Design",
      status: Invoice.StatusEnum.AUTHORISED
    }
  ]
};

const createdInvoicesResponse = await xero.accountingApi.createInvoices(activeTenantId, invoices);
const invoiceId = createdInvoicesResponse.body.invoices[0].invoiceID;

// CREATE a History Record
const historyRecords = {
  historyRecords: [
    {
      details: "This is a history record"
    }
  ]
};

await xero.accountingApi.createInvoiceHistory(activeTenantId, invoiceId, historyRecords);

To interact with Xero APIs, instantiate a XeroClient with your application credentials. The client provides access to various API sets like accountingApi, assetApi, projectApi, etc.

Required Configuration:

• clientId: Your Xero application client ID.
• clientSecret: Your Xero application client secret.

Optional Configuration:

• redirectUris: An array of callback URLs (not used for client_credentials flow).
• grantType: Set to 'client_credentials' for custom connections (not used for standard OAuth2 flows).
• scopes: An array of requested scopes (e.g., ['openid', 'profile', 'accounting.transactions']).
• state: Custom parameters for CSRF protection.
• httpTimeout: Request timeout in milliseconds.
• clockTolerance: Tolerance in seconds for token expiration checks.

const xero = new XeroClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUris: [`http://localhost:${port}/callback`],
  scopes: 'openid profile email accounting.settings accounting.transactions offline_access'.split(" "),
  httpTimeout: 3000,
  clockTolerance: 10
});

The XeroClient class provides the following core methods for managing authentication, connections, and token lifecycles:

| method | description |
| --- | --- |
| client.`initialize` | Initializes the Xero Client with the provided configuration |
| client.`buildConsentUrl` | Returns a url concatenated from the provided redirect uri, scope, and the issuer ( Xero identity authorize url) |
| client.`apiCallback`(callbackUrl) | Leverages openid-client library to exchange temporary auth code for token set |
| client.`disconnect`(connectionId) | Removes an individual tenant connection by connection ID |
| client.`readTokenSet` | Returns token set currently set on the Xero Client |
| client.`setTokenSet`(tokenSet) | Sets a specified token set on the Xero Client |
| client.`refreshToken` | Leverages openid-client library to refresh token set currently set on the Xero Client and returns updated token set |
| client.`revokeToken` | Revokes a users refresh token and removes all their connections to your app |
| client.`formatMsDate`(dateString) | Takes a date string and returns it formatted as an MS Date |
| client.`refreshWithRefreshToken`(clientId, clientSecret, refreshToken) | Refresh a token set without leveraging openid-client |
| client.`getClientCredentialsToken` | Get a token set without user intervention via the client credentials grant type for custom connections only |
| client.`updateTenants`(fullOrgDetails: boolean = true) | GET request to the /connections endpoint. Accepts a boolean to indicate whether or not to also make a GET request to the /organisations endpoint and map full org data to each connection object prior to returning the array of connections |