POST /delegation

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.

Â