Change the system a delivery comes from

PUT

/api/v1/delegations/{id}/source

const url = 'https://example.com/api/v1/delegations/example/source';
const options = {
  method: 'PUT',
  headers: {
    cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E',
    'Content-Type': 'application/json'
  },
  body: '{"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 PUT \
  --url https://example.com/api/v1/delegations/example/source \
  --header 'Content-Type: application/json' \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \
  --data '{ "source_id": "example", "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ] }'

Supplier: deliver an accepted delegation, or our open offer, from another system, or change its koppelingen (decisions #72). The system must serve every object of the delivery.

Authorizations

session
operator
dpop
operator
bearer
operator

Parameters

Path Parameters

required

string

The id of the delegation (urn:uuid:…).

Request Body^required

application/json

object

source_id

required

The system to deliver from.

string

links

The koppelingen of the objects in that system, when they differ from the default (an own id or key).

Array

A koppeling as the API shows it: the object, and how it differs.

object

local_id

The system’s own id of the building; the default is the object id.

string | null

auth_header_value

A key for this building only; the default is the system’s.

string | null

provides

What the system provides for this building: data (the default), topology (the indeling, decisions #71) or both.

string | null

object

required

The object id, e.g. nl.bag.pand.0014100040022681.

string

Example ^generated

{
  "source_id": "example",
  "links": [
    {
      "local_id": "example",
      "auth_header_value": "example",
      "provides": "example",
      "object": "example"
    }
  ]
}

Responses

200

OK.

application/json

A delegation as the management API shows it: the key of a binding masked.

object

required

string

role

required

Our side: delegator (rights holder) or delegate (supplier).

string

Allowed values: delegator delegate

initiated_by

required

Who started it (decisions #66): the rights holder asked, or the supplier offered. The other party accepts or rejects.

string

Allowed values: delegator delegate

state

required

requested, active, suspended, rejected, revoked or expired.

string

delegator_did

required

string

delegate_did

required

string

counterparty_address

required

string

dataset_id

required

string

title

required

string

description

required

string

building_id

string | null

objects

required

The objects this erkenning en aanwijzing covers (decisions #69).

Array<string>

points

Optionally only these points of the objects; None = all.

Array<string> | null

source_id

Supplier: the own source the backend binding was taken from.

string | null

profile

None: the data; the topology profile: the indeling (decisions #71).

string | null

basis

The basis on which the supplier delivers, e.g. a contract (V1).

string | null

actions

required

read and/or write.

Array<string>

valid_until

required

string format: date-time

note

string | null

controlplane

The rights holder’s control plane (DPS registration).

object | null

dataplane

The supplier’s data plane (DPS registration).

object | null

backend

One of:

null
object

null

Supplier only; never serialised with its secret (see masked).

object

base_url

required

The address of the system, e.g. https://bms.example.nl/api.

string

auth_header_name

The header that carries the key, e.g. X-Api-Key.

string | null

auth_header_value

The key; shown as ••••••, and sent back as such it stays as it was.

string | null

allowed_methods

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.

Array<string>

allowed_paths

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.

Array<string>

links

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

key

additional properties

How one object is reached in a system (decisions #72).

object

local_id

The system’s own id of the building; the default is the object id.

string | null

auth_header_value

A key for this building only; the default is the system’s.

string | null

provides

What the system provides for this building: data (the default), topology (the indeling, decisions #71) or both.

string | null

requested_by

string | null

decided_by

string | null

decided_at

string | null format: date-time

reason

string | null

history

required

The messages and states so far: at, state, message_type, direction, by, note, evidence_id.

Array<object>

object

created_at

required

string format: date-time

updated_at

required

string format: date-time

outbox

required

Our messages of this delegation that are not delivered yet.

Array<object>

A row of the outbox: a message of ours to a counterparty, until it is delivered or dropped (decisions #56).

object

required

integer format: int64

process_id

required

The negotiation, transfer or delegation the message belongs to.

string

kind

required

string

message_type

required

string

counterparty_did

required

string

url

required

string

evidence_id

required

string

status

required

string

attempts

required

integer format: int32

next_attempt_at

required

string format: date-time

last_error

string | null

response_status

integer | null format: int32

created_at

required

string format: date-time

resent_at

string | null format: date-time

delivered_at

string | null format: date-time

counterparty_did

required

string

counterparty_name

string | null

delegator_name

string | null

delegate_name

string | null

active

required

Active and within its period.

boolean

active_transfers

required

Transfers (rights holder) or data flows (supplier) that run now.

integer

asset

One of:

null
object

null

offers

Rights holder: how many offers the product has.

integer | null

existing_asset

Rights holder, open offer: a product of ours with the proposed id; reusable when its own delegation has ended.

object | null

transfers

Rights holder, single delegation: the transfers under it (id, state, counterparty_did, counterparty_name, updated_at).

Array<object> | null

object

flows

Supplier, single delegation: the data flows of the delivery, with requests_24h.

Array<object> | null

object

suggestions

Supplier, open request: existing bindings it could reuse (asset_id, title, building_id, backend).

Array<object> | null

object

Example

{
  "role": "delegator",
  "initiated_by": "delegator"
}

400

The request is not valid.

application/json

The body of every failed call to a management API.

object

error

required

object

code

required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string

message

required

For people; may change between versions.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

401

No valid session, DPoP-bound token or API key.

application/json

The body of every failed call to a management API.

object

error

required

object

code

required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string

message

required

For people; may change between versions.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

403

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

application/json

The body of every failed call to a management API.

object

error

required

object

code

required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string

message

required

For people; may change between versions.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

404

Not found.

application/json

The body of every failed call to a management API.

object

error

required

object

code

required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string

message

required

For people; may change between versions.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

409

Not an accepted delegation or open offer of ours as supplier.

application/json

The body of every failed call to a management API.

object

error

required

object

code

required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string

message

required

For people; may change between versions.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

Change the system a delivery comes from

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Example generated

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

Request Body^required

Example ^generated