# Service

This page contains an example implementation for a REST endpoint of a Service Provider, using the token obtained from the iSHARE [/token](/all-roles-common-endpoints/access-token-m2m.md) endpoint and the delegation evidence obtained from the [/delegation](/authorisation-registry-role/delegation-endpoint.md) endpoint.

### Delegation path example

In certain use cases, it could be relevant to provide information about a delegation path. A delegation path is the delegation of a delegation from one delegated party to another party. The iSHARE Framework does not specify how a delegation path should be provided to a Service Provider. More information about delegation paths is included in the [iSHARE Knowledge Base](https://trustbok.ishare.eu/apply-ishare/authorisation/delegation-chains).

An example of how a delegation path could be provided to the Service Provider is by using a header that contains party identifiers of the parties involved in the path. These identifiers can be used to obtain or evaluate a chain of delegation evidence.

```
Delegation-Path: [party-id-entitled-party, party-id-data-consumer, party-id-delegated-consumer, etc.]
```

## Example endpoint for Service Provider (parameters apply to other HTTP methods as well)

> This is an example service (business specific) endpoint to show how any Service Provider that adheres to iSHARE MUST apply iSHARE conformant OAuth to every iSHARE enabled service.\
> Request can make use of any HTTP method and can contain any extra headers. For convenience this documentation only defines the GET method. Parameters are undefined because they vary for each Service Provider due to their business specific logic. Note: Additional headers for security, statefulnes, application functionality could be added and is out of scope of this specification.

```json
{"openapi":"3.0.0","info":{"title":"iSHARE API specifications","version":"3.0"},"tags":[{"name":"Service Provider (Example)","description":"Example endpoints for the iSHARE Service Provider API."}],"servers":[{"description":"iSHARE test network base domain","url":"https://isharetest.net"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 authorization based on bearer token. MUST contain “Bearer “ + access token value. Must be provided if restricted endpoints are needed."}},"parameters":{"delegationEvidenceHeader":{"name":"delegationEvidence","description":"iSHARE delegation evidence regarding the requested service. The Service  Consumer can obtain this evidence from an Authorization Registry /  Entitled Party before requesting a specific service.","schema":{"type":"string"},"in":"header"},"serviceConsumerIdTokenSc":{"name":"serviceConsumerAssertion","description":"iSHARE specific optional client assertion. Used when a Service Consumer is requesting a service on behalf of another Service Consumer in a  'service broker' pattern. It is used to prove that the 'brokering'  Service Consumer indeed has had a request from the original Service  Consumer","schema":{"type":"string"},"in":"header"},"purpose":{"name":"LicensePurpose","description":"Optional iSHARE specific value describing the purpose of the license the Service Consuming Entity requests for the data in the service response","schema":{"type":"string"},"in":"header"},"serviceHeaders":{"name":"Service-Headers","description":"Any service specific headers","schema":{"type":"string"},"in":"header"}},"schemas":{"serviceContent":{"properties":{"serviceContent01":{"type":"string"},"serviceContentXX":{"type":"string"}}}}},"paths":{"/service":{"get":{"tags":["Service Provider (Example)"],"parameters":[{"$ref":"#/components/parameters/delegationEvidenceHeader"},{"$ref":"#/components/parameters/serviceConsumerIdTokenSc"},{"$ref":"#/components/parameters/purpose"},{"$ref":"#/components/parameters/serviceHeaders"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/serviceContent"}}},"description":"OK"}},"operationId":"service-example","summary":"Example endpoint for Service Provider (parameters apply to other HTTP methods as well)","description":"This is an example service (business specific) endpoint to show how any Service Provider that adheres to iSHARE MUST apply iSHARE conformant OAuth to every iSHARE enabled service.\nRequest can make use of any HTTP method and can contain any extra headers. For convenience this documentation only defines the GET method. Parameters are undefined because they vary for each Service Provider due to their business specific logic. Note: Additional headers for security, statefulnes, application functionality could be added and is out of scope of this specification."}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ishare.eu/service-provider-role/getting-started/service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.