> This is the Markdown of a Backed Help Centre page, https://admin.backed.giving/help/integrations/api-access.md. Every page is listed at https://admin.backed.giving/help/llms.txt.

> This page uses Backed's default terms, such as Funding Round and Application Template. An organisation may rename them, so read each as your organisation's own term if you've renamed it.

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

1. Go to `Settings > Profile and terms` and open the `API Access` tab.
2. Select `New Credential`.
3. Enter a `Name` that says which system uses it.
4. 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.
5. 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.
6. If you ticked a write scope, choose the Administrator it acts as under `Acts as`.
7. 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](power-bi.md).

## 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](api-c02-write-api-part-one-registrations-applications-no.md)
and [Write API: milestones, payments, contracts and files](api-c03-write-api-part-two-milestones-payments-contracts.md).

## 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

1. Select `Edit scopes` on its row.
2. Tick or untick scopes, and change `Acts as` if you need to.
3. 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

1. Select `Delete` on its row.
2. 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](developer-documentation.md).

## 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.

## See also

- [Integrations home](integrations-home.md)
- [Frequently asked questions about integrations](faq-integrations.md)
- [Reporting feed for analytics tools](power-bi.md)
- [Write API: registrations, applications, notes, tags and assignments](api-c02-write-api-part-one-registrations-applications-no.md)
- [Write API: milestones, payments, contracts and files](api-c03-write-api-part-two-milestones-payments-contracts.md)
- [Developer documentation](developer-documentation.md)