Which access you need, who sets it up in Spendesk, and which scopes to ask for.
Before your first call, you need an access that fits what you want to do, created by the right person, with the right scopes. This page tells you which one.
Which access do you need?
| You want to… | Access | Who sets it up |
|---|---|---|
| Connect your own tools to your company's Spendesk: scripts, BI, spreadsheets, an ERP sync | API key (company-level) | An Account Owner or Admin, in Settings → Integrations → Manage API access |
| Do the same for several entities of a group at once | Organisation-level API key | An organisation owner, in Settings → Integrations → API Access Management — see Organisation-level access |
| Build an integration used by many Spendesk customers | OAuth2 app — each customer approves the connection | The Spendesk partnerships team — see How to Authenticate |
| Ask questions about your data in Claude, ChatGPT, Dust or Langdock | MCP connection — no API key | An Admin or Account Owner sets it up once; Controllers and Account Owners use it — see Connect an AI assistant (MCP) |
| Try the API before going live | Demo account credentials, on https://public-api.demo.spendesk.com | Ask for them when you request API access |
Create an API key
- In Spendesk, an Account Owner or Admin opens Settings → Integrations → Manage API access — API Access Management for an organisation-level key.
- Tick the scopes the key needs — the table below lists them per use. A key only carries the scopes ticked here: a token cannot ask for more.
- Choose an expiry date: a key is valid for up to one year. Note it, and create the next key before it expires.
- Keep the client ID and secret in a password manager or your platform's secret store, never in code or a shared document.
Then get a token and make your first call: see the Quickstart, or fill in clientId and clientSecret in our Postman collection.
Scopes for each use
Tick only what you need. Scopes starting with experimental: need access to experimental features first (next section).
| Use | Scopes |
|---|---|
| Read spend data: payables, receipts, settlements, fees, wallet — What is Spend Data?, Retrieving Spend Data | payable:read, payable-attachment:read, settlement:read, bank-fee:read, wallet-load:read, wallet-summary:read |
| Reference data: users, suppliers, cost centers, analytical fields, expense categories | user:read, supplier:read, cost-center:read, analytical-field:read, expense-category:read |
| Export a month of spend to a spreadsheet | experimental:payable-search:read, supplier:read, user:read, cost-center:read |
| List the invoices due this week | experimental:invoice:read, user:read |
| Month-end close checklist | experimental:payable-search:read, experimental:invoice:read, experimental:transaction:read, user:read |
| Check the wallet balance | wallet-summary:read, wallet-load:read |
| Exporting accounting data | experimental:accounting-export:read, payable:read or experimental:payable-search:read, experimental:accounting:update |
| Building an accounting integration | The scopes of each flow, listed in the guide |
| Using webhooks | experimental:webhooks:read, experimental:webhooks:write |
| Several entities, with an organisation-level key | experimental:company:read, plus the scopes above |
Every scope is described in Scopes.
Access to experimental features
Endpoints marked experimental — invoices, payable search, accounting exports, purchase orders, cards and transactions, webhooks, organisation-level access — are available on request, and may still change (see Versioning & Deprecation).
Ask your Customer Success Manager, or write to [email protected]. To speed things up, say:
- your company or organisation name, and whether you need company-level or organisation-level access;
- the scopes you need, from the table above;
- whether you also need demo credentials to build and test first.
Once access is granted, tick the new scopes on the API key — see Create an API key.
If a call is refused
| Response | Likely cause | What to do |
|---|---|---|
401 when requesting a token | Wrong client ID or secret, or a scope the key does not have | Check the credentials — and the key's expiry date; request only scopes ticked on the key |
403 on an endpoint | The token does not carry the endpoint's scope | Check the endpoint's Allowed Scopes in the API reference; add the scope to the key, after requesting experimental access if needed |
400 mentioning X-Company-Id | An organisation-level token called a v1 endpoint without saying which company | Send the X-Company-Id header — see Organisation-level access |
403 on Get Companies | A company-level token: listing companies needs an organisation-level key | Use an organisation-level key, or work with your own company only |
See Error Handling for the error format.
Last checked against the Spendesk demo environment on 29 September 2026.