Start a delegation
const url = 'https://example.com/api/v1/delegations';const options = { method: 'POST', headers: { cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E', 'Content-Type': 'application/json' }, body: '{"delegate_did":"example","delegator_did":"example","dataset":{"id":"example","title":"example","description":"example","keywords":["example"],"building_id":"example","objects":["example"],"points":["example"],"profile":"example"},"objects":["example"],"points":["example"],"profile":"example","basis":"example","actions":["example"],"valid_until":"2026-04-15T12:00:00Z","note":"example","backend":{"base_url":"example","auth_header_name":"example","auth_header_value":"example","allowed_methods":["example"],"allowed_paths":["example"],"links":{"additionalProperty":{"local_id":"example","auth_header_value":"example","provides":"example"}}},"source_id":"example","links":[{"local_id":"example","auth_header_value":"example","provides":"example","object":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/delegations \ --header 'Content-Type: application/json' \ --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \ --data '{ "delegate_did": "example", "delegator_did": "example", "dataset": { "id": "example", "title": "example", "description": "example", "keywords": [ "example" ], "building_id": "example", "objects": [ "example" ], "points": [ "example" ], "profile": "example" }, "objects": [ "example" ], "points": [ "example" ], "profile": "example", "basis": "example", "actions": [ "example" ], "valid_until": "2026-04-15T12:00:00Z", "note": "example", "backend": { "base_url": "example", "auth_header_name": "example", "auth_header_value": "example", "allowed_methods": [ "example" ], "allowed_paths": [ "example" ], "links": { "additionalProperty": { "local_id": "example", "auth_header_value": "example", "provides": "example" } } }, "source_id": "example", "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ] }'As rights holder, with delegate_did: ask a supplier to deliver a dataset of ours from its data plane; the product stays out of the catalog until the supplier accepts. As supplier, with delegator_did: offer a rights holder to deliver one of its datasets from a system of ours (source_id). The other party accepts or rejects (decisions #66).
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Rights holder: the supplier asked to deliver.
Supplier: the rights holder offered delivery (decisions #66).
The dataset (product) a delegation is about.
object
The product id; left out: made from the title.
The objects the delivery covers (decisions #69); building_id is the
older single object.
Only these points of the objects; left out = all.
The topology profile: a delegation for the indeling (decisions #71).
The objects and points may also come next to the dataset.
The basis on which the supplier delivers (V1).
read and/or write.
At least an hour and at most five years from now.
No longer accepted: a delivery comes from a system (decisions #72).
object
The address of the system, e.g. https://bms.example.nl/api.
The header that carries the key, e.g. X-Api-Key.
The key; shown as ••••••, and sent back as such it stays as it was.
Methods the data plane lets through, e.g. ["GET"] for reading or
["GET", "POST", "PATCH"] for reading and steering. At least one: an
empty list lets nothing through.
Path patterns the data plane lets through (* one segment, ** the
rest), e.g. api/sites/4711/**, or ["**"] for the whole API. At
least one, except on a Buildinglinks system, whose koppelingen fill
them (v1/buildings/{object}/**): an empty list lets nothing through.
Koppelingen that differ from the default, per object (decisions #72): the data plane routes the building to the system’s own id and key.
object
How one object is reached in a system (decisions #72).
object
The system’s own id of the building; the default is the object id.
A key for this building only; the default is the system’s.
What the system provides for this building: data (the default),
topology (the indeling, decisions #71) or both.
Supplier: the system (source) it delivers from.
Supplier: the koppelingen of the objects in that system, when they differ from the default (own id, own key).
A koppeling as the API shows it: the object, and how it differs.
object
The system’s own id of the building; the default is the object id.
A key for this building only; the default is the system’s.
What the system provides for this building: data (the default),
topology (the indeling, decisions #71) or both.
The object id, e.g. nl.bag.pand.0014100040022681.
Example generated
{ "delegate_did": "example", "delegator_did": "example", "dataset": { "id": "example", "title": "example", "description": "example", "keywords": [ "example" ], "building_id": "example", "objects": [ "example" ], "points": [ "example" ], "profile": "example" }, "objects": [ "example" ], "points": [ "example" ], "profile": "example", "basis": "example", "actions": [ "example" ], "valid_until": "2026-04-15T12:00:00Z", "note": "example", "backend": { "base_url": "example", "auth_header_name": "example", "auth_header_value": "example", "allowed_methods": [ "example" ], "allowed_paths": [ "example" ], "links": { "additionalProperty": { "local_id": "example", "auth_header_value": "example", "provides": "example" } } }, "source_id": "example", "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ]}Responses
Section titled “Responses”Created.
A delegation as the management API shows it: the key of a binding masked.
object
Our side: delegator (rights holder) or delegate (supplier).
Who started it (decisions #66): the rights holder asked, or the supplier offered. The other party accepts or rejects.
requested, active, suspended, rejected, revoked or expired.
The objects this erkenning en aanwijzing covers (decisions #69).
Optionally only these points of the objects; None = all.
Supplier: the own source the backend binding was taken from.
None: the data; the topology profile: the indeling (decisions #71).
The basis on which the supplier delivers, e.g. a contract (V1).
read and/or write.
The rights holder’s control plane (DPS registration).
The supplier’s data plane (DPS registration).
Supplier only; never serialised with its secret (see masked).
object
The address of the system, e.g. https://bms.example.nl/api.
The header that carries the key, e.g. X-Api-Key.
The key; shown as ••••••, and sent back as such it stays as it was.
Methods the data plane lets through, e.g. ["GET"] for reading or
["GET", "POST", "PATCH"] for reading and steering. At least one: an
empty list lets nothing through.
Path patterns the data plane lets through (* one segment, ** the
rest), e.g. api/sites/4711/**, or ["**"] for the whole API. At
least one, except on a Buildinglinks system, whose koppelingen fill
them (v1/buildings/{object}/**): an empty list lets nothing through.
Koppelingen that differ from the default, per object (decisions #72): the data plane routes the building to the system’s own id and key.
object
How one object is reached in a system (decisions #72).
object
The system’s own id of the building; the default is the object id.
A key for this building only; the default is the system’s.
What the system provides for this building: data (the default),
topology (the indeling, decisions #71) or both.
The messages and states so far: at, state, message_type,
direction, by, note, evidence_id.
object
Our messages of this delegation that are not delivered yet.
A row of the outbox: a message of ours to a counterparty, until it is delivered or dropped (decisions #56).
object
The negotiation, transfer or delegation the message belongs to.
Active and within its period.
Transfers (rights holder) or data flows (supplier) that run now.
Rights holder: how many offers the product has.
Rights holder, open offer: a product of ours with the proposed id;
reusable when its own delegation has ended.
Rights holder, single delegation: the transfers under it (id,
state, counterparty_did, counterparty_name, updated_at).
object
Supplier, single delegation: the data flows of the delivery, with
requests_24h.
object
Supplier, open request: existing bindings it could reuse (asset_id,
title, building_id, backend).
object
Example
{ "role": "delegator", "initiated_by": "delegator"}The request is not valid.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}No valid session, DPoP-bound token or API key.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}The caller lacks the role this operation needs; or a change with the session cookie came from a page of another site (cross_site_request, decisions #83).
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}Conflicts with the current state.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}The authority could not be reached.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}