Xero API integration with managed OAuth. Manage contacts, invoices, payments, accounts, and run financial reports. Use this skill when users want to interact with Xero accounting data. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Access the Xero API with managed OAuth authentication. Manage contacts, invoices, payments, bank transactions, and run financial reports.
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/xero/api.xro/2.0/Contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
```
https://gateway.maton.ai/xero/{native-api-path}
```
Replace `{native-api-path}` with the actual Xero API endpoint path. The gateway proxies requests to `api.xero.com` and automatically injects your OAuth token and Xero-Tenant-Id header.
All requests require the Maton API key in the Authorization header:
```
Authorization: Bearer $MATON_API_KEY
```
**Environment Variable:** Set your API key as `MATON_API_KEY`:
```bash
export MATON_API_KEY="YOUR_API_KEY"
```
1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key
Manage your Xero OAuth connections at `https://ctrl.maton.ai`.
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=xero&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'xero'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
**Response:**
```json
{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "xero",
"metadata": {}
}
}
```
Open the returned `url` in a browser to complete OAuth authorization.
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
If you have multiple Xero connections, specify which one to use with the `Maton-Connection` header:
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/xero/api.xro/2.0/Contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
If omitted, the gateway uses the default (oldest) active connection.
#### List Contacts
```bash
GET /xero/api.xro/2.0/Contacts
```
#### Get Contact
```bash
GET /xero/api.xro/2.0/Contacts/{contactId}
```
#### Create Contact
```bash
POST /xero/api.xro/2.0/Contacts
Content-Type: application/json
{
"Contacts": [{
"Name": "John Doe",
"EmailAddress": "[email protected]",
"Phones": [{"PhoneType": "DEFAULT", "PhoneNumber": "555-1234"}]
}]
}
```
#### List Invoices
```bash
GET /xero/api.xro/2.0/Invoices
```
#### Create Invoice
```bash
POST /xero/api.xro/2.0/Invoices
Content-Type: application/json
{
"Invoices": [{
"Type": "ACCREC",
"Contact": {"ContactID": "xxx"},
"LineItems": [{
"Description": "Service",
"Quantity": 1,
"UnitAmount": 100.00,
"AccountCode": "200"
}]
}]
}
```
#### List Accounts
```bash
GET /xero/api.xro/2.0/Accounts
```
#### List Payments
```bash
GET /xero/api.xro/2.0/Payments
```
#### List Bank Transactions
```bash
GET /xero/api.xro/2.0/BankTransactions
```
#### Profit and Loss
```bash
GET /xero/api.xro/2.0/Reports/ProfitAndLoss?fromDate=2024-01-01&toDate=2024-12-31
```
#### Balance Sheet
```bash
GET /xero/api.xro/2.0/Reports/BalanceSheet?date=2024-12-31
```
#### Trial Balance
```bash
GET /xero/api.xro/2.0/Reports/TrialBalance?date=2024-12-31
```
```bash
GET /xero/api.xro/2.0/Organisation
```
```javascript
const response = await fetch(
'https://gateway.maton.ai/xero/api.xro/2.0/Contacts',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);
```
```python
import os
import requests
response = requests.get(
'https://gateway.maton.ai/xero/api.xro/2.0/Contacts',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
```
| Status | Meaning |
|--------|---------|
| 400 | Missing Xero connection |
| 401 | Invalid or missing Maton API key |
| 429 | Rate limited (10 req/sec per account) |
| 4xx/5xx | Passthrough error from Xero API |
**When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:**
1. Check that the `MATON_API_KEY` environment variable is set:
```bash
echo $MATON_API_KEY
```
2. Verify the API key is valid by listing connections:
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
Leave a review
No reviews yet. Be the first to review this skill!