search

Capabilities

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.

hashtag
Retrieves iSHARE capabilities

get

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.

Authorizations
AuthorizationstringOptional

OAuth 2.0 authorization based on bearer token. MUST contain “Bearer “ + access token value. Must be provided if restricted endpoints are needed.

Responses
chevron-right
200

OK

application/json
get
/capabilities
200

OK

hashtag
Response Model

The model of the capabilities_token JWT response is available on the iSHARE OpenAPI documentationarrow-up-right. 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_info Object. Root level. Contains information about capabilities.

    • party_id String. Contained in capabilities_info. Party ID, also known as EORI number of the party which provides the capabilities info.

    • ishare_roles Array of Objects. Contained in capabilities_info. Contains array of role objects that provide the information about the roles of the party in iSHARE.

      • role String. Contained in ishare_roles. Should be on the following values: ServiceConsumer, ServiceProvider, EntitledParty, AuthorisationRegistry, IdentityProvider, IdentityBroker, iShareSatellite.

    • supported_versions Array of Objects. Contained in capabilities_info. Contains information about supported version endpoints for each version.

      • version String. Contained in supported_versions. Version of the system which is under support.

        • supported_features Array of Objects. Contained in supported_versions. Contains a list of supported features for different access levels.

          • public Array of Objects. Contained in supported_features. Contains supported public features.

            • id String. Contained in the object of public. Unique identifier of the feature.

            • feature String. Contained in the object of public. Friendly name of the feature.

            • description String. Contained in the object of public. Short description about the feature.

            • url String. Contained in the object of public. URL to the feature.

            • token_endpoint String. 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.

          • restricted Array 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.

hashtag
Example request

hashtag
Example response

The response contains an encoded JWT, which looks like this:

After decoding, the example content of the JWT looks like this:

circle-info

Note

This page must be considered part of the iSHARE Trust Framework

PreviousAccess token (M2M)NextiSHARE JWT

Last updated