The /capabilities endpoint is required for every participant that provides services:
iSHARE Satellite
Authorisation Registry
Service Provider
Identity Provider
The endpoint returns iSHARE capabilities of the iSHARE party. The server response is an iSHARE signed JSON Web Token.
Depending on whether or not an Access Token is provided to the capabilities endpoint, the endpoint must return public or public and restricted endpoints. in detail:
If an access token IS NOT provided
Return public endpoints, including the Access Token endpoint
If an access token IS provided
Return public endpoints, including the Access Token endpoint
Return restricted endpoints
Any endpoints that are not intended to be part of the capabilities to be used by iSHARE roles (out of scope of iSHARE) must not be included in the capabilities endpoint return.
Response Model
The model of the capabilities_token JWT response is available on Swaggerhub. For convenience the model of the parties_info object, contained within the token, is described below:
Decoded capabilities_token parameters:
It contains iSHARE compliant JWT claims, however if an access token is not provided, then aud claim should be omitted while signing JWT. In addition to that it also contains the following parameters:
capabilities_infoObject. Root level.
Contains information about capabilities.
party_idString. Contained in capabilities_info.
Party ID, also known as EORI number of the party which provides the capabilities info.
ishare_rolesArray of Objects. Contained in capabilities_info.
Contains array of role objects that provide the information about the roles of the party in iSHARE.
roleString. Contained in ishare_roles.
Should be on the following values: ServiceConsumer, ServiceProvider, EntitledParty, AuthorisationRegistry, IdentityProvider, IdentityBroker, iShareSatellite.
supported_versionsArray of Objects. Contained in capabilities_info.
Contains information about supported version endpoints for each version.
versionString. Contained in supported_versions.
Version of the system which is under support.
supported_featuresArray of Objects. Contained in supported_versions.
Contains a list of supported features for different access levels.
publicArray of Objects. Contained in supported_features.
Contains supported public features.
idString. Contained in the object of public.
Unique identifier of the feature.
featureString. Contained in the object of public.
Friendly name of the feature.
descriptionString. Contained in the object of public.
Short description about the feature.
urlString. Contained in the object of public.
URL to the feature.
token_endpointString. Contained in the object of public. Optional.
URL where access token for the feature could be retrieved. This is optional because if feature is access token, it is not needed to mention it twice.
restrictedArray of Objects. Contained in supported_features. Optional.
Contains supported restricted features. The structure and parameters are exactly the same as defined in public parameter above. It should only be shown to the parties which provided a valid access token. If an access token was not provided or restricted endpoints does not exist, this value can be not returned, empty or null.
Example request
> Authorization: Bearer IIeDIrdnYo2ngwDQYJKoZIhvcNAQELBQAwSDEZMBcGA1UEAwwQaVNIQ
GET /capabilities
Example response
The response contains an encoded JWT, which looks like this:
The /capabilities endpoint is required for every participant that provides services. The endpoint returns iSHARE capabilities (supported versions & optional features) of the iSHARE party.
The capabilities endpoint should only return the public endpoints if no access token is provided. If an access token is provided, the capabilities endpoint will also provide the restricted endpoints. A party may also have private endpoints, which are endpoints for their own internal organization, also known as endpoints that are implemented, but not to share with the others. These endpoints are not within the scope of iSHARE and should not be returned to other iSHARE parties.
Server response is an iSHARE signed JSON Web Token. Please refer to the models 'jwt_header' and 'jwt_payload_capabilities_token' which indicate what the decoded response will look like.