API access

A credential lets another system, such as your finance or reporting system, connect to your organisation through the Backed API. Create one under Settings > Profile and terms, on the API Access tab.

Before you start

You need the Can access Organisation settings permission to see the tab, and the permission to manage integrations to create, edit or delete credentials. Without it you can see the credentials but not change them. To choose who a credential acts as, you also need Can edit permissions. To give the Read reporting feed scope, you also need the permission to generate reports.

Create a credential

Go to Settings > Profile and terms and open the API Access tab.
Select New Credential.
Enter a Name that says which system uses it.
Tick Include bank account numbers only if the system needs applicants' full bank account numbers. Only people who can edit applicants or view payments can give this, and it can't be changed later.
Under Scopes, tick what else the system may do. Read is always ticked. Tick Read reporting feed if the system is an analytics tool such as Power BI or Tableau.
If you ticked a write scope, choose the Administrator it acts as under Acts as.
Select Create.

Credential created shows the Client ID and Client Secret. Copy the Client Secret now with Copy Client Secret: you will not see it again, and it can't be recovered. Then select I have copied it.

Give the Client ID and Client Secret to the other system. It uses them to get access tokens for the API. To report on your records in Power BI or another analytics tool, see Reporting feed for analytics tools.

Scopes

Every credential can read. One more read scope lets an analytics tool read the reporting feed:

Read reporting feed: read the OData reporting feed at /odata/v4/ on your organisation's address, which Power BI, Tableau and Excel load as an OData feed. Only someone who can generate reports can give it, so the box is locked for anyone else. It reads, so it doesn't need an Administrator to act as. A credential without it is refused by the feed.

A write scope lets a credential change records too:

Write registrations: create and update registrations, and add their members.
Write applications: move applications between stages, add notes and set tags.
Write assessments: assign assessors to an assessment round.
Write post-award records: create and approve milestones, mark payments paid, and execute or terminate contracts.
Write files: upload files and attach them to records.

Give a credential only the scopes its system needs. A credential you had before scopes existed keeps only Read.

The routes each write scope opens, and what each refuses, are in Write API: registrations, applications, notes, tags and assignments and Write API: milestones, payments, contracts and files.

Who a credential acts as

A credential with a write scope acts as one enabled Administrator you choose under Acts as. Every change it makes runs with that Administrator's permissions and data access rules, so it can't do anything they couldn't, and the audit log records the credential and the Administrator together. Only someone with Can edit permissions can choose or change this person. If that Administrator is later disabled, the credential can still read but every write is refused until you choose someone else.

Edit a credential's scopes

Select Edit scopes on its row.
Tick or untick scopes, and change Acts as if you need to.
Select Save.

The change applies to the credential's next request. If someone else changed the credential while you were editing, you are asked to reload first.

Idempotency keys

Every request that creates or changes something (POST, PUT or PATCH) must carry an Idempotency-Key header with a value your system makes up, unique to that change. If the request is sent again with the same key and the same body within 24 hours, Backed returns the first answer and makes no second change, so a retry after a dropped connection is safe. The same key with a different body is refused with 422, and a request with no key is refused with 400.

If-Match

A PATCH that updates a record must carry an If-Match header holding the record's lock_version, as your system last read it. If someone changed the record since, the update is refused with 412 precondition_failed and nothing changes: read the record again, then retry.

See your credentials

The list shows each credential's Name, Client ID, Scopes, who it Acts as, Created (and by whom) and Last used. A credential that can read bank account numbers is marked Bank account numbers. Until you create one, the page says No credentials yet.

Delete a credential

Select Delete on its row.
Confirm with Delete.

Anything using it loses access. Its access tokens stop working at once, on their next request. This can't be undone. To replace a secret, create a new credential, move the system to it, then delete the old one.

Developer documentation

Select Developer documentation on the API Access tab to open the developer site, at https://backed.giving/developers, in a new tab. It has the reference for every route, with request and response examples, guides, the Event catalogue and the Changelog. The OpenAPI document that describes the whole API is at your organisation's address plus /api/v2/openapi.json, and on the site. Neither needs a credential. See Developer documentation.

Versions and deprecation

The current version of the Backed API is v2, and every request goes to a path under /api/v2/. Any other version path, such as /api/v1/, answers 404 with {"error":"not_found"}.

Breaking changes come only in a new version. A change that could break a system already connected, such as removing or renaming a field, a route or a format, is published under a new version path. The version you use keeps working as it is.
A superseded version stays for at least 12 months. When a new version is published, the previous one is deprecated and stays available for at least 12 months after that date before it is removed.
You are told by email. The Administrators of every organisation with an API credential are emailed when a version's deprecation starts, and again 3 months before it is removed.
Responses say so too. Every response from a deprecated version carries a Deprecation header with the date its deprecation started, a Sunset header with the date it will be removed, and a Link header pointing to this section. A response from the current version carries neither.