Skip to content

Switch to Backbone API v2 #381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 24, 2025
Merged

Switch to Backbone API v2 #381

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3831b73
feat: recommend to use Backbone v7
britsta Oct 24, 2025
3534d87
feat: remove approvedAt and approvedByDevice properties of IdentityDe…
britsta Oct 24, 2025
264fa07
feat: rename status "Approved" of IdentityDeletionProcess to "Active"
britsta Oct 24, 2025
25fa9a7
chore: run Excel script for updating use case metadata
britsta Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 11 additions & 13 deletions _docs_integrate/data-model-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,19 +217,17 @@ If you want to [delete your Identity]({% link _docs_integrate/delete-identities.
Up until then, the data about the deletion process is stored in an object called IdentityDeletionProcess.
It is possible to [cancel an IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) that hasn't reached the end of its grace period, yet.
Since cancelled IdentityDeletionProcesses are stored, you can reach a situation in which there are multiple IdentityDeletionProcesses associated with the same Identity.
Note, however, that at all times there can only be at most one **active IdentityDeletionProcess**, i.e. with `"Approved"` as `status`, per Identity.

| Name | Type | Description | Remarks |
| ----------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | |
| status | `"Approved"` \| `"Cancelled"` | The status of the IdentityDeletionProcess. <br>{::nomarkdown}<ul><li>Approved: the IdentityDeletionProcess was <a href="{% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}">initiated directly by the Identity itself</a> and is active. Unless it is cancelled, the Identity will be deleted by the end of the grace period.</li><li>Cancelled: the IdentityDeletionProcess was cancelled and is no longer active.</li></ul>{:/} | |
| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | |
| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="IdentityDeletionProcess" %} | |
| approvedAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was approved. | |
| approvedByDevice | `string` \| `undefined` | The ID of the Device that approved the IdentityDeletionProcess. | |
| gracePeriodEndsAt | `string` \| `undefined` | A timestamp that describes when the Identity will be permanently deleted. Up until this moment, it is possible to cancel the IdentityDeletionProcess. | |
| cancelledAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was cancelled. | |
| cancelledByDevice | `string` \| `undefined` | The ID of the Device that cancelled the IdentityDeletionProcess. | |
Note, however, that at all times there can only be at most one **active IdentityDeletionProcess**, i.e. with `"Active"` as `status`, per Identity.

| Name | Type | Description | Remarks |
| ----------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | |
| status | `"Active"` \| `"Cancelled"` | The status of the IdentityDeletionProcess. <br>{::nomarkdown}<ul><li>Active: the IdentityDeletionProcess was <a href="{% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}">initiated directly by the Identity itself</a> and is active. Unless it is cancelled, the Identity will be deleted by the end of the grace period.</li><li>Cancelled: the IdentityDeletionProcess was cancelled and is no longer active.</li></ul>{:/} | |
| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | |
| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="IdentityDeletionProcess" %} | |
| gracePeriodEndsAt | `string` \| `undefined` | A timestamp that describes when the Identity will be permanently deleted. Up until this moment, it is possible to cancel the IdentityDeletionProcess. | |
| cancelledAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was cancelled. | |
| cancelledByDevice | `string` \| `undefined` | The ID of the Device that cancelled the IdentityDeletionProcess. | |

# Local Types

Expand Down
8 changes: 4 additions & 4 deletions _docs_integrate/delete-identities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ However, Integrators of Connectors can still delete their Identity by using [Con
## IdentityDeletionProcesses

From a technical perspective, the process of Identity deletion is described by a data object of type [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). It can be uniquely identified by its `id`.
An IdentityDeletionProcess can have `"Approved"` or `"Cancelled"` as its `status`.
If an IdentityDeletionProcess has `"Approved"` as `status`, it is also referred to as an **active IdentityDeletionProcess**.
An IdentityDeletionProcess can have `"Active"` or `"Cancelled"` as its `status`.
If an IdentityDeletionProcess has `"Active"` as `status`, it is also referred to as an **active IdentityDeletionProcess**.
There can be at most one active IdentityDeletionProcess per Identity.
There are three [use cases]({% link _docs_integrate/use-cases.md %}) for getting one or more already existing [IdentityDeletionProcesses]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess):

Expand All @@ -55,11 +55,11 @@ Whenever a new [IdentityDeletionProcess]({% link _docs_integrate/data-model-over
### Self-Initiated Identity Deletion

An Identity can actively trigger its own process of deletion by executing the [Initiate IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}) use case.
Successful execution leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Approved"` as `status`.
Successful execution leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Active"` as `status`.
The Identity is immediately in deletion and will be irreversibly deleted from the Backbone once the end of the associated grace period of the IdentityDeletionProcess specified within its `gracePeriodEndsAt` property has been reached.
Within the grace period, the [Cancel IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) use case can be applied by the Identity if it no longer wants to be deleted.
In this case, the `status` of the IdentityDeletionProcess changes to `"Cancelled"`.
Trying to cancel an IdentityDeletionProcess that does not have `"Approved"` as `status` causes an error with `error.runtime.identityDeletionProcess.noApprovedIdentityDeletionProcess` as [error code]({% link _docs_integrate/error-codes.md %}) to be thrown.
Trying to cancel an IdentityDeletionProcess that does not have `"Active"` as `status` causes an error with `error.runtime.identityDeletionProcess.noApprovedIdentityDeletionProcess` as [error code]({% link _docs_integrate/error-codes.md %}) to be thrown.
Furthermore, please note that the use of the [Initiate IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}) use case is not permitted if there is already an active IdentityDeletionProcess.
The corresponding [error code]({% link _docs_integrate/error-codes.md %}) is given by `error.runtime.identityDeletionProcess.activeIdentityDeletionProcessAlreadyExists`.

Expand Down
7 changes: 7 additions & 0 deletions _docs_integrate/migration-from-v6-to-v7.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,11 @@ The step-by-step instructions can be consulted to start the migration to version
- The `database.dbNamePrefix` field of the [database configuration]({% link _docs_operate/configuration.md %}#database) was removed. Before, it defaulted to `acc-`. If a database called `acc-connector` is to be accessed, the value of the `database.dbName` field must be set to `acc-connector` instead of `connector` only.
- To support additional authentication methods beyond API key authentication, the `apiKey` field was replaced by the `authentication.apiKey.keys.<key-id>.key` parameter of the [authentication configuration]({% link _docs_operate/configuration.md %}#authentication). The `authentication.apiKey.keys.<key-id>.scopes` field provides a convenient way to configure the permissions that apply when the API key identified by `<key-id>` is used.
- Additionally, the support for the `API_KEY` [environment variable]({% link _docs_operate/configuration.md %}#environment-variables) has been removed, that could be used to define an API key using a short environment variable. As an alternative, the `authentication.apiKey.keys.<key-id>.key` configuration property can be set using an environment variable.
- It must be ensured that a [Backbone](https://github.com/nmshd/backbone/tags) is used which is compatible with version 7 of the Connector.
Even though a Backbone of version 6 can still be used, it is recommended to update to version 7 of the Backbone due to the new features and bug fixes provided.
Appropriate Backbone credentials can be specified in the fields `transportLibrary.baseUrl`, `transportLibrary.platformClientId` and `transportLibrary.platformClientSecret` of the [Backbone configuration]({% link _docs_operate/configuration.md %}#transportlibrary).
The URL `<baseUrl of Backbone>/api/v2/version` can be accessed to validate the version of the Backbone.
Please note that version 7 of the Backbone only supports version 2 of its API and no longer version 1.

### Removed and Changed Data Structures

Expand All @@ -60,6 +65,8 @@ The step-by-step instructions can be consulted to start the migration to version
The property `reference` was introduced to group the property `truncated` with the additional property `url`, improving structure and better organizing related data.
- The `title` property of the [File]({% link _docs_integrate/data-model-overview.md %}#file) became optional and should no longer be relied upon to be set.
- The `ownershipToken` property of the [TransferFileOwnershipRequestItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershiprequestitem) became mandatory. This ensures that the ownership of the original File on the Backbone is transferred instead of applying a copy-based workaround. If the ownership of a [File]({% link _docs_integrate/data-model-overview.md %}#file) ought to be transferred, that doesn't have an `ownershipToken` yet, it will need to be [regenerated]({% link _docs_use-cases/use-case-transport-regenerate-file-ownership-token.md %}).
- The properties `approvedAt` and `approvedByDevice` of the [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) have been removed.
Furthermore, renaming `"Approved"` to `"Active"` resulted in a change of an IdentityDeletionProcess `status`.
- All data structures around the Attribute listener feature, including the LocalAttributeListener, the RegisterAttributeListenerRequestItem, and the RegisterAttributeListenerAcceptResponseItem, were removed.

### Changed Behavior of Known Features
Expand Down
4 changes: 2 additions & 2 deletions _docs_operate/backbone-security-considerations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,8 @@ There is no authorization set up. So if you have the API-Key, you can access all

The Consumer API supports configuring quotas on different write-actions to limit how often a user can execute those. These quotas can be defined per identity. However, there are some endpoints that allow anonymous access and that therefore cannot be rate limited by quotas. These endpoints currently are:

- `POST /api/v1/Challenges`
- `POST /api/v1/Identities`
- `POST /api/v2/Challenges`
- `POST /api/v2/Identities`

When operating the Backbone's Consumer API, you should make sure that the endpoints mentioned above are not abused by malicious users by implementing rate limiting on the network level.

Expand Down
Loading