You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 2
Next »
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 must be 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.
The trust framework catalogue 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 |
---|
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 . |
Example request body for a succesful POST /delegation call
{
"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.
The trust framework catalogue MUST include a delegation_token
including of a delegationEvidence
object in a response to a successful GET calls to the /delegation
endpoint
See below for an example response to a POST /delegation call (based on iSHARE v2.0, see link)
Example of a response to a succesful POST /delegation call
< 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.