Universal.Xero.Client 12.4.0

Universal.Xero.Client

Type-safe, generated wrapper for the Xero API with simplified authentication.

Still uses the official SDK behind the scenes, but provides a saner API.

Getting Started

Installation

dotnet add package Universal.Xero.Client

Authentication

Universal.Xero.Client supports all OAuth2 flows for Xero authentication:

1. Authorization Code Flow (Web Applications)

Standard OAuth2 flow for web applications with a backend server:

// Exchange authorization code for access token and create client
var client = await XeroClient.CreateWithAuthorizationCodeAsync(
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    code: "authorization-code-from-callback",
    redirectUri: "https://yourapp.com/callback",
    tenantId: "tenant-id"
);

2. PKCE Flow (Mobile Apps & SPAs)

Recommended for public clients where you can't securely store a client secret:

// Generate code verifier before authorization (store it securely)
string codeVerifier = GenerateCodeVerifier(); // Your implementation

// After receiving the authorization code, create client
var client = await XeroClient.CreateWithPkceAsync(
    clientId: "your-client-id",
    code: "authorization-code-from-callback",
    codeVerifier: codeVerifier,
    redirectUri: "yourapp://callback",
    tenantId: "tenant-id"
);

3. Client Credentials Flow (Machine-to-Machine)

For server-to-server authentication without user interaction:

var client = await XeroClient.CreateWithClientCredentialsAsync(
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    scope: "accounting.transactions accounting.contacts"
);

4. Refresh Token Flow

Renew expired access tokens without user interaction:

var client = await XeroClient.CreateWithRefreshTokenAsync(
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    refreshToken: "stored-refresh-token",
    tenantId: "tenant-id"
);

5. Direct Access Token (Custom Connections)

If you already have an access token from elsewhere:

// Standard OAuth Apps (multi-tenant)
var client = new XeroClient(tenantId, accessToken);

// Custom Connections (single organization)
var client = new XeroClient(accessToken);

Working with Tokens

If you need more control over token management, you can obtain tokens separately:

// Get token without creating client
IXeroToken token = await XeroClient.GetTokenByAuthorizationCodeAsync(
    clientId, clientSecret, code, redirectUri);

// Access token properties
string accessToken = token.AccessToken;
string refreshToken = token.RefreshToken;
DateTime expiresAt = token.ExpiresAtUtc;
List<Tenant> tenants = token.Tenants;

// Create client later
var client = new XeroClient(tenantId, token.AccessToken);

Available token methods:

• GetTokenByAuthorizationCodeAsync() - Standard OAuth2 authorization code flow
• GetTokenByAuthorizationCodePkceAsync() - PKCE flow for public clients
• GetTokenByRefreshTokenAsync() - Refresh an expired token
• GetTokenByClientCredentialsAsync() - Machine-to-machine authentication

Usage

using Universal.Xero.Client;

// Create client with your credentials
var client = new XeroClient(tenantId, accessToken);

// Access any Xero API
// Any class named XApi from the official SDK -> XClient.
var invoices = await client.AccountingClient.GetInvoicesAsync();
var employees = await client.PayrollAuClient.GetEmployeesAsync();
var projects = await client.ProjectClient.GetProjectsAsync();

// Get a specific resource
var invoice = await client.AccountingClient.GetInvoiceAsync(invoiceId);

Features

• Fully Generated: Automatically generated from the official Xero SDK
• Type-Safe: Full IntelliSense support with preserved XML documentation - 1:1 match with official SDK but with quality of life improvements
• All OAuth2 Flows: Support for authorization code, PKCE, client credentials, and refresh token flows
• Organized by API: Separate clients for Accounting, Payroll, Projects, Assets, etc. - same as official SDK
• Simplified Auth: No need to pass access tokens and tenant IDs to every method call - batteries included

Available Clients

• AccountingClient - Core accounting operations (invoices, contacts, payments, etc.)
• AppStoreClient - App marketplace integration
• AssetClient - Fixed asset management
• BankFeedsClient - Bank feed management
• FilesClient - File storage and attachments
• FinanceClient - Financial reporting
• IdentityClient - OAuth connections
• PayrollAuClient - Australian payroll
• PayrollNzClient - New Zealand payroll
• PayrollUkClient - UK payroll
• ProjectClient - Project tracking and time entries

Example: Complete OAuth Flow

// 1. Redirect user to Xero authorization URL (implement in your app)
string authUrl = $"https://login.xero.com/identity/connect/authorize?...";

// 2. User authorizes and returns with code
// 3. Exchange code for token and create client
var client = await XeroClient.CreateWithAuthorizationCodeAsync(
    clientId, clientSecret, code, redirectUri, tenantId);

// 4. Use client
var invoices = await client.AccountingClient.GetInvoicesAsync();

// 5. When token expires, refresh it
var newClient = await XeroClient.CreateWithRefreshTokenAsync(
    clientId, clientSecret, storedRefreshToken, tenantId);