Connecting to Xero Practice Manager

This guide walks you through everything you need to connect your Xero Practice Manager (XPM) account to StructureGram. Once connected, you can sync entities and relationships between XPM and StructureGram, push data to XPM, and reconcile differences between the two systems.

Prerequisites

Before you begin, make sure you have:

An active Xero Practice Manager subscription — StructureGram connects to XPM via the Xero API. You need a current XPM account with at least read access to client data.
A StructureGram account — you must be logged in and have an active organisation (tenancy) selected.
Xero user permissions — your Xero user account must have permission to authorise third-party app connections. If your organisation restricts API access, contact your Xero administrator.

Step 1: Enable Two-Factor Authentication

StructureGram requires two-factor authentication (2FA / MFA) for all users before they can connect to Xero. This protects sensitive client data by ensuring only verified users can access the integration.

If you haven't set up 2FA yet

Navigate to Account → Security (or click the security settings link shown on the Integrations page)
Click Enable Two-Factor Authentication
Follow the prompts to register an authenticator app (e.g. Google Authenticator, Authy, Microsoft Authenticator, 1Password)
Enter the verification code from your authenticator app to complete enrolment

If you already have 2FA enabled

You'll be prompted to enter your 2FA code when you initiate the connection. This is a one-time verification for the current session.

Note: The 2FA requirement applies to all users in your organisation who need to access Xero integration features. Each user must enrol individually.

Step 2: Connect to Xero

Once 2FA is enabled, you can connect your Xero account.

Navigate to Account → Integrations
In the Xero XPM Integration card, click Connect to Xero XPM
If prompted, enter your 2FA code
You'll be redirected to Xero's authorisation page

Authorising StructureGram in Xero

On Xero's authorisation page:

Sign in to your Xero account (if you're not already signed in)
Select your Practice Manager organisation — if you have multiple Xero organisations, choose the one that has Practice Manager enabled
Review the permissions — StructureGram requests:
- Practice Manager client read — to read client, group, and relationship data from XPM
- Practice Manager client write — to create and update clients and relationships in XPM (used for push and reconciliation apply)
- OpenID / profile / email — to verify your identity
- Offline access — to maintain the connection without requiring re-authentication every time
Click Allow Access to grant StructureGram access to your XPM data

After authorisation, you'll be redirected back to StructureGram. A success message will confirm the connection, and the integration card will show a green Connected badge.

What happens during connection

When you complete the OAuth flow, StructureGram:

Stores your connection securely — access tokens are encrypted at rest and never exposed to the browser
Sets up MFA requirement — your user profile is flagged to require 2FA for all future integration actions
Runs automatic discovery — StructureGram immediately fetches the list of available XPM groups so you can start linking right away

Step 3: Test Your Connection

After connecting, it's a good idea to verify that everything is working.

On the Integrations page, click Test Organisation API
If the test succeeds, you'll see a green Organisation API: Success badge
If the test fails, check:
- Whether your Xero session has expired (re-authenticate if needed)
- Whether your XPM subscription is still active
- Whether your Xero user has the required permissions

The test makes a lightweight API call to XPM to confirm that StructureGram can read client data from your account.

Step 4: Link XPM Groups to StructureGram

With your connection active, the next step is to link XPM groups to StructureGram groups. This tells StructureGram which XPM group maps to which StructureGram group for syncing.

There are two ways to link groups:

Option A: From the Import Groups page

This is the recommended approach if you're setting up the integration for the first time.

Click Import Groups on the Integrations page (or navigate to Data → Import Groups from XPM)
You'll see a catalog of all available XPM groups discovered from your account
For each XPM group you want to sync:
- Click Link to create a new StructureGram group and link it to the XPM group
- Or click Link to Existing and choose an existing StructureGram group from the dropdown
Once linked, you can immediately start syncing the group's entities and relationships

Only import the groups that you want to create StructureGrams for. The XPM API can take time to sync, so you should limit the load to only what you need. If you try and link all of your groups at once, this is likely to cause the connection to fail.

Option B: From an existing StructureGram group

If you already have a StructureGram group and want to connect it to XPM:

Navigate to Groups and select the group you want to link
Open the group's XPM tab
Select the XPM group from the available list and click Link

Group linking rules

Each XPM group can only be linked to one StructureGram group (and vice versa)
You can unlink a group at any time without deleting any data
Linking a group does not automatically sync data — you need to run a sync separately
If the XPM group list is stale, click Refresh to re-run discovery and fetch the latest groups from XPM

After Connecting: What's Next?

Once connected and linked, you have three main workflows available:

Sync (Pull)

Pull entities and relationships from XPM into StructureGram. This is ideal for the initial import and for keeping StructureGram up to date with XPM changes.

See Xero Practice Manager Sync for the full guide.

Push

Send StructureGram entities and relationships to XPM. Use this when you've created or updated data in StructureGram and want it reflected in XPM.

See Push to Xero Practice Manager for the full guide.

Reconciliation

Compare data between StructureGram and XPM, review differences side by side, and choose how to resolve each conflict. This gives you full control over which direction data flows.

See XPM Reconciliation for the full guide.

Managing Your Connection

Viewing connection status

The Integrations page shows:

Connection status — whether you're connected and to which Xero organisation
Linked groups count — how many groups are linked to XPM
Discovery cache — when the XPM group catalog was last refreshed

Disconnecting

To disconnect from Xero:

Navigate to Account → Integrations
Click Disconnect
Confirm the disconnection in the dialog

Disconnecting:

Revokes StructureGram's access tokens with Xero
Removes the MFA requirement for Xero integration actions
Does not delete any synced data, group links, or entity mappings — your data remains intact
You can reconnect at any time and resume where you left off

Reconnecting

If your connection expires or you need to re-authenticate:

Navigate to Account → Integrations
Click Connect to Xero XPM again
Complete the OAuth flow as before

Existing group links and entity mappings are preserved, so a reconnection picks up exactly where the previous connection left off.

Token Management

StructureGram handles token management automatically:

Access tokens expire after a short period (set by Xero). StructureGram automatically refreshes them before they expire.
Refresh tokens are valid for 60 days. If you don't use the integration for more than 60 days, you'll need to reconnect.
All tokens are encrypted at rest using server-side encryption. They are never sent to or stored in the browser.

Troubleshooting

"Enable two-factor authentication to connect to Xero"

You need to set up 2FA before connecting. Go to Account → Security and follow the enrolment steps.

"Authorization was denied"

You clicked "Deny" on Xero's authorisation page, or the request timed out. Try the connection again and click "Allow Access" when prompted.

"No Xero organizations found"

Your Xero account doesn't have any connected organisations, or the organisation doesn't have Practice Manager enabled. Check your Xero subscription and ensure XPM is active.

"Security validation failed"

The OAuth state parameter didn't match. This can happen if:

The connection attempt took too long (state cookies expire after 10 minutes)
You have multiple browser tabs open with different connection attempts
Browser cookies were cleared during the flow

Try again in a single tab.

"Failed to complete connection"

A generic error during the OAuth callback. Check:

Your internet connection
Whether Xero's services are operational (check Xero Status)
Browser console for more details

Test connection fails after connecting

Your access token may have expired and failed to refresh — try disconnecting and reconnecting
Your XPM subscription may have lapsed — verify in your Xero account
Xero may be experiencing service issues — check Xero Status

No XPM groups appear after connecting

Discovery runs automatically on connection, but may fail silently if XPM is temporarily unavailable. Click Refresh on the Import Groups page to re-run discovery.

Help & Documentation