Retrieves a list of all participants to the requesting party from the trust framework catalogue.

The trust framework catalogue MUST support a GET call to a /parties endpoint to retrieve a list of DSGO participants (in an array of parties_info objects).

Request

Authorization

An access token must be used in GET calls to the /parties endpoint. For more information, see Access Token.

The trust framework catalogue MUST validate that a GET call to a /parties endpoint includes the “Authorization" header according to RFC 6750 and includes 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 GET request to the /parties endpoint contains the parameters as defined in the table below

The trust framework catalogue MUST validate that the HTTP body of a GET request to the /parties endpoint contains at least a single parameter.

Parameter		Type	Description
`name`	Optional	String	Used to search by a party’s name. MUST be the party’s name or contain a single `*` as wildcard instead
`party_id`	Optional	String	Used to search by a party’s identifier. MUST contain an Organisation ID, containing an EORI or KvK number, or contain a single `*` as wildcard
`certified_only`	Optional	Boolean	Used to search all certified parties. MUST be equal to `null`, `false` or `true`. If `null` is provided, then it will not affect the query and will return both certified and non-certified parties. If `false` is provided, then the query will return non-certified parties. If `true` is provided, the query will return certified parties.
`active_only`	Optional	Boolean	Used to search all active parties. MUST be equal to `null`, `false` or `true`. If `null` is provided, then it will not affect the query and will return both active and inactive parties. If `false` is provided, then the query will return inactive parties. If `true` is provided, then the query will return active parties.
`certificate_subject_name`	Optional	Boolean	MUST be `subjectName` as encoded in the X.509 certificate, which corresponds with the party that is being requested from the trust framework catalogue. Used by the catalogue to match the certificate identifier. Subject name attributes may be in any order, but all of them MUST be included and separated by comma, if at least one subject attribute is missing - information won't be returned. Only returns info if combined with the valid Organisation ID associated to it.
`page`	Optional	Integer	Used for navigation in case the result contains more than 10 parties, MUST contain an integer.
`date_time`	Optional	String	Date and time for which the information is requested. MUST be according to ISO 8601, following the timestamp conventions. If provided, the result becomes final and therefore MUST be cacheable.

Example request body for a succesful GET /parties call

> Authorization: Bearer IIeDIrdnYo2ngwDQYJKoZIhvcNAQELBQAwSDEZMBcGA1UEAwwQaVNIQ

GET /parties?
    eori=EU.EORI.NL000000004&
    certificate_subject_name=C=NL, SERIALNUMBER=EU.EORI.NL000000004, CN=iSHARE Test Authorization Registry&
    active_only=true

Responses

200 OK

Successful, the response contains data providing the requested parties information in a party_token. The party_token is a signed JWT, which contains the claims as defined in the Authentication JWT, and additionally contains a parties_info object.

The trust framework catalogue MUST include a party_token including of an (array of) parties_info objects in a response to a successful GET calls to the /parties endpoint

Example of a response to a succesful GET /parties call

< Content-Type: application/json

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

Decoded party_token payload:

{
  "iss": "EU.EORI.NL000000000",
  "sub": "EU.EORI.NL000000000",
  "jti": "77e8179fbfe6469eb64c054da26a77c3",
  "iat": 1589282112,
  "exp": 1589282142,
  "aud": "EU.EORI.NL000000001",
  "party_info": {
    "party_id": "EU.EORI.NL000000004",
    "party_name": "AskMeAnything Authorization Registry",
    "adherence": {
      "status": "Active",
      "start_date": "2018-04-26T00:00:00",
      "end_date": "2020-07-25T00:00:00"
    },
    "certifications": [
      {
        "role": "AuthorisationRegistry",
        "start_date": "2018-01-04T00:00:00",
        "end_date": "2020-02-02T00:00:00",
        "loa": 3
      }
    ],
    "capability_url": "https://ar.isharetest.net/capabilities"
  }
}

400 Bad Request

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