> ## Documentation Index
> Fetch the complete documentation index at: https://holder.docs.fiskil.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Schema

> Use the power of OpenAPI to build your Open Data environment

## OpenAPI

To configure your custom Open Data environment you share an [OpenAPI](https://swagger.io/specification/) Schema with Fiskil that defines your resource server API.
This schema contains:

* Your endpoints
* Permissions required to access each endpoint

## Endpoint Requirements

### `customerId` path parameter

The paths in your endpoints must contain `/customer/{customerId}` so Fiskil can request the data for the user who authorised sharing. For example:

```yaml theme={null}
paths:
  /v1/customer/{customerId}/pay:
    get:
      description: Shows the users pay information e.g. salary, pay frequency, Year To Date (YTD) earnings.
      operationId: getPayInformation
      parameters:
        - description: ID of a customer.
          explode: false
          in: path
          name: customerId
          required: true
          schema:
            type: string
          style: simple
```

The `customer/{customerId}` path parameter is required to ensure data from the correct customer is accessed.

Third parties requesting data from your environment don't provide the `customer/{customerId}` in their request, Fiskil trims this from the
API endpoint. For example: you might
provide an OpenAPI definition with the following endpoints:

* `/v1/customer/{customerId}/pay`
* `/v1/customer/{customerId}/payslips`
* `/v1/customer/{customerId}/payslips/{id}`

Your Fiskil Open Data API will expose the following endpoints:

* `/v1/pay`
* `/v1/payslips`
* `/v1/payslips/{id}`

The customer ID in the request to your server is set based on the user associated with the access token used to request the data.

### `authorized_account_ids` query parameter

During the Consent Flow, end users are prompted to authorise the accounts they wish to make available for data sharing. This list of accounts is populated by the [List accounts available for sharing API](/api-reference/cdr/auth-customer-accounts).

To ensure that only data from authorised accounts is shared, Fiskil will specify the authorised account IDs when Fiskil requests data from all of your resource server APIs using a query string parameter: `authorized_account_ids`.

```yaml theme={null}
paths:
  /v1/customer/{customerId}/pay:
    get:
      description: Shows the users pay information e.g. salary, pay frequency, Year To Date (YTD) earnings.
      operationId: getPayInformation
      parameters:
        # ... other parameters
        - description: List of authorized account IDs to filter response by.
          explode: false
          in: query
          name: authorized_account_ids
          required: true
          schema:
            type: array
            items:
              type: string
```

The authorised account IDs are provided as a comma-separated list of strings. Your resource server API endpoints must:

1. Read the `authorized_account_ids` URL query parameter value
2. Split the value by `,` to get the authorised account IDs
3. Filter the requested data so that only resources belonging to an authorised account are returned from your API

## Scopes

Open ID Connect Scopes are used to authorise the sharing of specific datasets from your users. Your
users review the scopes being requested by third parties so they know exactly what data they are
sharing. Fiskil uses two OpenAPI extensions to define the scopes required to access your data.

1. Data Sharing endpoints must have a `x-fiskil-scopes` extension defining the scopes that must be authorised by the user to access the data
2. The `info` block must contain a `x-fiskil-scopeset` extension that defines the list of scopes supported and descriptions of them

For example:

```yaml theme={null}
info:
  title: Mock Payroll API
  x-fiskil-scopeset:
    "payroll:pay:read":
      cluster_language: "Payroll - Read pay information"
      permission_language:
        - "Annual Salary"
        - "Pay Frequency"
        - "YTD Earnings"
paths:
  /v1/customer/{customerId}/pay:
    get:
      description: Shows the users pay information e.g. salary, pay frequency, Year To Date (YTD) earnings.
      summary: Get Pay Information
      operationId: getPayInformation
      parameters:
        - description: ID of a customer.
          explode: false
          in: path
          name: customerId
          required: true
          schema:
            type: string
          style: simple
      x-fiskil-scopes:
        - 'payroll:pay:read'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePayInformation'
          description: Success
      summary: Get Pay Information
```

In this example the `x-fiskil-scopeset` extension on the `info` element lists the available scopes: `payroll:pay:read`. The `cluster_language` field presents a high-level description of the data that is shared. The `permissions_language` field
shows the exact pieces of data that fall under this scope.

The `x-fiskil-scopes` extension on the `getPayInformation` operation shows that the `payroll:pay:read` scope is required if a third party wants to access the `pay` dataset.

This information is shown to the end user during authorisation

<img src="https://mintcdn.com/fiskil/IMRNPUDCfaHUjBpY/img/custom-scope-example.png?fit=max&auto=format&n=IMRNPUDCfaHUjBpY&q=85&s=df9069ecaafad3156792a26017debd48" alt="Scope Preview" width="520" height="641" data-path="img/custom-scope-example.png" />

## Uploading your OpenAPI Specification

You provide your OpenAPI Specification to Fiskil through the Fiskil Data Provider console. Navigate to the
[Resource Server Settings Menu](https://console.fiskil.com/data-holder/settings/resource-server) and upload your specification.

The Fiskil platform will validate your OpenAPI document against the requirements listed above. Once you've uploaded your
specification, develop your [resource server](http://localhost:3000/docs/configure/resource-server-settings) to implement
your OpenAPI specification.

After completing both these steps your environment is ready for testing.

Download a [full example](/content/payroll.yaml) of a Fiskil-compatible OpenAPI definition including customer ID path parameters and scope definitions

## Extension Reference

### `x-fiskil-scopeset`

**Parent element**: `info`
**Type**: `Map<string, object>`
**Object properties**:

```yaml theme={null}
cluster_language: string
permission_language: List<string>
```

**Example**:

```yaml theme={null}
info:
  x-fiskil-scopeset:
    payroll:pay:read:
      cluster_language: Payroll - Read pay information
      permission_language:
        - Annual Salary
        - Pay Frequency
        - YTD Earnings
```

### `x-fiskil-scopes`

**Parent element**: `method`
**Type**: `List<string>`

All values within the list must be present as a key in the `x-fiskil-scopeset` map.

**Example**:

```yaml theme={null}
paths:
  /v1/customer/{customerId}/pay:
    get:
      description: Shows the users pay information e.g. salary, pay frequency, Year To Date (YTD) earnings.
      x-fiskil-scopes:
        - payroll:pay:read
      # Remaining method content excluded...
```