List delegations

GET

/api/v1/delegations

const url = 'https://example.com/api/v1/delegations';
const options = {
  method: 'GET',
  headers: {cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/api/v1/delegations \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E

Deliveries on behalf of a rights holder (erkenning en aanwijzing), as rights holder and as supplier.

Authorizations

session
viewer
dpop
viewer
bearer
viewer

Parameters

Query Parameters

role

string

delegator (we are the rights holder) or delegate (we deliver).

Responses

200

OK.

application/json

A page of a list. next_cursor is null on the last page.

object

items

required

Array

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

next_cursor

Pass as cursor for the next page.

string | null

Example

{
  "items": [
    {
      "role": "delegator",
      "initiated_by": "delegator"
    }
  ]
}

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"
  }
}