Used to obtain delegation evidence from a data entitled party or authorisation register. Delegation evidence can be used in future data service requests to data service providers if delegation is enabled in their data service.

Parties MUST support a POST call to a /delegation endpoint to retrieve delegation evidence (in a delegationEvidence object).

Request

Authorization

An access token is used in POST calls to the /delegation endpoint. For more information, see Access Token.

Parties MUST validate that a POST call to a /delegation endpoint includes the Authorization header according to RFC 6750 and contains a valid access token

Parameters

For information about the parameters that are common to the trust framework’s API’s see Generic API Requirements.

Parties MUST validate that the HTTP body of a POST request to the /delegation endpoint contains the parameters as defined in the table below

Parameter				Type	Description

Parameter				Type	Description
`delegationRequest`			Required	Object	Object MUST contain `policyIssuer`, `target` and `policySets` objects, and may contain the `delegation_path` and `previous_steps` arrays as described below
	`policyIssuer`		Required	String in `delegationRequest`	MUST contain a valid Organisation ID of the delegator (data entitled party), containing an EORI or KvK number.
	`target`		Required	Object in `delegationRequest`	Object MUST contain an `accessSubject`. No other elements are allowed. It makes the entire delegation evidence applicable only to this `accessSubject`.
		`accessSubject`	Required	String in `target`	MUST contain a valid Organisation ID of the delegate (the data service consumer that receives the delegated rights), containing an EORI or KvK number.
	`policySets`		Required	Array in `delegationRequest`	MUST contain one or more `policySet` objects with an indication for further delegation (see /delegation for more information). Note that multiple `policySet` objects within one `delegationEvidence` MUST not restrict each other, but rather offer a mechanism to express additional rights. They MUST be evaluated in a `permit-override` manner, allowing a `Permit` if only one of the `policySet` objects evaluates to `Permit`.
	`delegation_path`		Optional	Array in `delegationRequest`	Optional array used in a situation where multiple delegation policies need to be linked together. MUST contain one or more valid Organisation ID, containing an EORI or KvK number
	`previous_steps`		Optional	Array in `delegationRequest`	Optional array used for one or more pieces of evidence such that the client has legitimate reason to request delegation evidence. MUST contain a previous `delegationEvidence` object or `client_assertion` for a single step. May contain an array for multiple steps. The minimum is a `client_assertion` value of the `accessSubject`, for example if the data service provider requests `delegationEvidence` for an authorization in which he is neither the `policyIssuer` nor the `accessSubject`.

{
  "delegationRequest": {
    "policyIssuer": "EU.EORI.NL123456789",
    "target": {
      "accessSubject": "EU.EORI.NL987654321"
    },
    "policySets": [ "object" ]
  },
  "delegation_path": [ "string" ],
  "previous_steps": [ "string" ]
}

Responses

200 OK

Successful, the response contains data providing the requested parties information in a delegation_token. The delegation_token is a signed JWT, which contains the claims as defined in the Authentication JWT, and additionally contains a delegationEvidence object. Find the definition of the delegationEvidence object here.

See below for an example response to a POST /delegation call (based on iSHARE v2.0, see link)

< Content-Type: application/json

{
  "delegation_token": "eyJ4NWMiOlsiTUlJRWlEQ0NBbkNnQXdJQkFnSUllRElyZG5ZbzJuZ3dEUVlKS29aSWh2Y05BUUVMQlFBd1NERVpNQmNHQTFVRUF3d1FhVk5JUVZKRlZHVnpkRU5CWDFSTVV6RU5NQXNHQTFVRUN3d0VWR1Z6ZERFUE1BMEdBMVVFQ2d3R2FWTklRVkpGTVFzd0NRWURWUVFHRXdKT1REQWVGdzB4T1RBeU1UVXhNVFEyTlRoYUZ3MHlNVEF5TVRReE1UUTJOVGhhTUVreEhEQWFCZ05WQkFNTUUybFRTRUZTUlNCVFkyaGxiV1VnVDNkdVpYSXhIREFhQmdOVkJBVVRFMFZWTGtWUFVra3VUa3d3TURBd01EQXdNREF4Q3pBSkJnTlZCQVlUQWs1TU1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBMFJvb2hlUEwwMk52NEJaVEoza3A3bktzaHNtanJjcjhNQmFBaFFwWlpBc2dUQWxtUWlDVFBtM2M4cVlQcU4rVHVnZ0ZXQ05uKzlXNTRDNVVHcXNJd3RYVGszWWV4QXdaNG9qUlJ0bzhsMUhQRFZBUzZXdlc3NEFDTlpsRWdHd2pyQ0d5MitNNVFQN083d0IwVDZvRkJvZlJ3SFpHemdidFNiU1FodXF3VXhmMEdaSTh4QWwyL0dUSDI1VmZwOVQ3MUpFcG9aOWtzUDNDSWk1QkhrbGJUNUdLeEVPRmZkTU11cFg3bVduTlFiTHh1UXBBdEdDdW9yR2ZQRkU3RjVldkUxem9wd2NlQTVGc0UxTGFCUnF0K0VPcFBJbVNhalIwMmJjaEs5alM2bllFV3MvRlpHTHRKYWxsNUwzU25aTTZPaFd4TStsS0d6Rkt3NVRJWE45RE13SURBUUFCbzNVd2N6QU1CZ05WSFJNQkFmOEVBakFBTUI4R0ExVWRJd1FZTUJhQUZCWTg1eURwMXBUdkgrV2k4Ymo4dnVyZkxEZUJNQk1HQTFVZEpRUU1NQW9HQ0NzR0FRVUZCd01CTUIwR0ExVWREZ1FXQkJSZndpalQ3NWRJS1BsRkMvQ3RSRHFVS1g5VE5qQU9CZ05WSFE4QkFmOEVCQU1DQmFBd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dJQkFLNFBXVHEvZHF0Vm0rNFdDZDFLUUo0dGorbjRjY0lBWUxETXFZU0JKc042UTJjdE1SQy8rK3lNL293UEhCcmlUendXL2pvQXBOUGVaaDFJVFRnU3phMzhtM2h4b0RxMXV4NkhWR3lLNVFDUW9qRmRsZWM3dE9IbG1jYnV5VjRDRXlNWmJHK3lMbVZESTNxNTNWQVBnV3ZLSWkyUlVwc1BOdzJsbzZINjZ2SE5wNWZpcEIvdEU0Q0RsYS9UYU41MWxOM2xYT3c0bHRiWmJ6YmQ2TXhJbEVDUWZKSDVlUHJpcGFrSmhuaVZrWnZRVmthS0FlcFNYMGFEWUxPcFFRbmV0RFdab1ZKS0FzR0VMM0hMaWhxWXNEejcvQlQzRHdUMEtDNSs5OGdqR1p3dkx3ZXRKOTZLWFRBRTUwMmYzak95UDdERDZ1SytKS2d2UVp5dkk1L0V1cDBUdE5sUmZKeThhZDhweCszOG9JeEdBbGJzS29XbXowb2FNR0MrbFZHTlAyTTQ4TTdWa3RCVHB5bXF4Vnd0VGt2TVBqWldIS2xYdDJXMzNtTktHakpTOTVJNXZxT0tQV1NTc1dkSlJZSkNsbUVybWlkTlczMWxXQVZQcjFpU1M0SlhEdllQTENQNDRhNGVkMEdhV1pSdi9iK0QyK1FVZ09iOFN6bWpQdmYvMkdOdHFXUmR5WXRYWjl2eDAzNGkrWEYveWU4c2lOK1grd0ZIdFJ1bXRzd2Irc2NRZjRmVTZNaktCS1VzUERBUkFHakhqNXhIQkRqcTg0bmpHdVFjbDBoYlMzK1pTVjROcWtKSVVzMkxVdDlFdjFYN2FCNy85NUVYQWNnTlhkM0tQVm0zcDhORDc1QXFNMEZHUUVhUXlPd3FLY3FUQ2xKQ3VmR3NVWTRzN3JXUiJdLCJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJFVS5FT1JJLk5MMDAwMDAwMDAwIiwic3ViIjoiRVUuRU9SSS5OTDAwMDAwMDAwMCIsImp0aSI6Ijc3ZTgxNzlmYmZlNjQ2OWViNjRjMDU0ZGEyNmE3N2MzIiwiaWF0IjoxNTg5MjgyMTEyLCJleHAiOjE1ODkyODIxNDIsImF1ZCI6IkVVLkVPUkkuTkwwMDAwMDAwMDEiLCJwYXJ0eV9pbmZvIjp7InBhcnR5X2lkIjoiRVUuRU9SSS5OTDAwMDAwMDAwNCIsInBhcnR5X25hbWUiOiJBc2tNZUFueXRoaW5nIEF1dGhvcml6YXRpb24gUmVnaXN0cnkiLCJhZGhlcmVuY2UiOnsic3RhdHVzIjoiQWN0aXZlIiwic3RhcnRfZGF0ZSI6IjIwMTgtMDQtMjZUMDA6MDA6MDAiLCJlbmRfZGF0ZSI6IjIwMjAtMDctMjVUMDA6MDA6MDAifSwiY2VydGlmaWNhdGlvbnMiOlt7InJvbGUiOiJBdXRob3Jpc2F0aW9uUmVnaXN0cnkiLCJzdGFydF9kYXRlIjoiMjAxOC0wMS0wNFQwMDowMDowMCIsImVuZF9kYXRlIjoiMjAyMC0wMi0wMlQwMDowMDowMCIsImxvYSI6M31dLCJjYXBhYmlsaXR5X3VybCI6Imh0dHBzOi8vYXIuaXNoYXJldGVzdC5uZXQvY2FwYWJpbGl0aWVzIn19.U2nIhL2600VX1uaMdJ_uUJky_Q8WSSRDKcbmeYrL_GGHifptwlB00uwj1uWmbUbd5KlYIYio-lPX1BwMzYmVXLC6ZydkI7kIsdQypiSEXGT6U2KIlTO2EyF3CU6EY6iBzuVtvyupbDVPkKzDVh8thE5cepCS_FAsZZvxYXfeWGjVoKRpHtAIGq8reTIgEE_9w-p6Toa970ERJ01Lcn3xpDPp-FNLobmMa_mM6Vn4m6WjvMxr77coO54GDJ6FM70egChiBHJSjUGqDaBUgebdAFh3AQ8TfYJntka9DiNVFiY5Y_HqecBmKW_DiokT40DiljXEhRy6YVLSHjxOKa81TQ"
}

Decoded delegation_token payload:

{
  "iss": "EU.EORI.NL000000004",
  "sub": "EU.EORI.NL000000001",
  "jti": "d8a7fd7465754a4a9117ee28f5b7fb60",
  "iat": 1591966224,
  "exp": 1591966254,
  "aud": "EU.EORI.NL000000001",
  "delegationEvidence": {
    "notBefore": 1541058939,
    "notOnOrAfter": 2147483647,
    "policyIssuer": "EU.EORI.NL000000005",
    "target": {
      "accessSubject": "EU.EORI.NL000000001"
    },
    "policySets": [
      {
        "maxDelegationDepth": 0,
        "target": {
          "environment": {
            "licenses": [
              "DSGO.0001"
            ]
          }
        },
        "policies": [
          {
            "target": {
              "resource": {
                "type": "GS1.CONTAINER",
                "identifiers": [
                  "180621.CONTAINER-Z"
                ],
                "attributes": [
                  "GS1.CONTAINER.ATTRIBUTE.ETA",
                  "GS1.CONTAINER.ATTRIBUTE.WEIGHT"
                ]
              },
              "environment": {
                "dataServiceProviders": [
                  "EU.EORI.NL000000003"
                ]
              },
              "actions": [
                "DSGO.READ",
                "DSGO.CREATE",
                "DSGO.UPDATE",
                "DSGO.DELETE"
              ]
            },
            "rules": [
              {
                "effect": "Permit"
              }
            ]
          }
        ]
      }
    ]
  }
}

400 Bad Request

When the Authorization header is provided, but the token format is invalid (for example, not Bearer). Additionally, a 400 should be returned when the provided access token is valid, but query parameters are either invalid or none of them were provided.

401 Unauthorized

When Authorization header is either missing, invalid or the access token has already expired.