# Delegation Policy

The Delegation Policy Request endpoint is an API endpoint that can be used to request the creation of a delegation policy.

{% hint style="info" %}
The `POST` request to `/delegationPolicy` is an **OPTIONAL** endpoint. For more information on **OPTIONAL** specifications, see [functional requirements per role.](https://framework.ishare.eu/detailed-descriptions/functional/functional-requirements-per-role)
{% endhint %}

## Request creation of a delegation policy

> The Delegation policy request endpoint is an API endpoint that receives  policy creation requests. The POST body accepts a JWT token: the Policy  Creation Request Token.

```json
{"openapi":"3.0.0","info":{"title":"iSHARE API specifications","version":"3.0"},"tags":[{"name":"Authorisation Registry (Optional)","description":"Optional endpoints for the iSHARE Authorisation Registry 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."}},"schemas":{"delegationPolicyCreationRequest":{"title":"DelegationPolicyCreationRequest","required":["delegationPolicyRequestToken"],"type":"object","properties":{"delegationPolicyRequestToken":{"type":"string","format":"application/jwt"}}}}},"paths":{"/delegationPolicy":{"post":{"tags":["Authorisation Registry (Optional)"],"description":"The Delegation policy request endpoint is an API endpoint that receives  policy creation requests. The POST body accepts a JWT token: the Policy  Creation Request Token.","operationId":"create-delegation-policy","summary":"Request creation of a delegation policy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/delegationPolicyCreationRequest"}}},"required":true},"responses":{"200":{"description":"OK: The requested policy is created."},"401":{"description":"Unauthorized: When Authorization header is either missing, invalid  or token has already expired."},"403":{"description":"Forbidden: This error message is return when a policy creation request  could not be processed after rules evaluation. The requested policy  does not comply with the rules as set by the Entitled Party."},"500":{"description":"Server Error: When the Authorization Registry was unable to process  the request"}}}}}}
```

### Request

#### Headers

* `Authorization`\
  **String**. <mark style="color:red;">(Required)</mark>\
  OAuth 2.0 authorisation based on a bearer token. MUST contain “Bearer “ + access token value. How to retrieve the access token can be found in the [Access Token Endpoint section](https://gitlab.com/ishare-foundation/cab/developer-portal/-/blob/main/all-roles-common-endpoints/access-token-m2m%20\(1\).md).
* `Content-Type`\
  **String**.\
  Defines the request body content type. MUST be equal to *application/json*.

#### Parameters

The body of the request contains [iSHARE Compliant JWT](https://dev.ishare.eu/reference/ishare-jwt) delegationPolicyRequestToken. Besides the default attributes (iss, sub, aud, etc.), it contains the following attributes. The model of the delegation PolicyRequestToken [is available on the iSHARE OpenAPI documentation](https://openapi.ishare.eu/index.html?version=2.2#/jwtPayloadDelegationPolicyRequestToken). For convenience, the model is also described below.

* `delegationPolicyRequest`\
  **Object**. Root level. <mark style="color:red;">(Required)</mark>\
  Contains information about the delegation policy that is requested to create.
  * `notBefore`\
    **Integer**. Contained in `delegationPolicyRequest`. <mark style="color:red;">(Required)</mark>\
    Unix timestamp indicating the start of the validity period of the requested delegation policy.
  * `notOnOrAfter`\
    **Integer**. Contained in `delegationPolicyRequest`.\
    Unix timestamp indicating the end of the validity period of the requested delegation policy.
  * `policyRequestor`\
    **String**. Contained in `delegationPolicyRequest`. <mark style="color:red;">(Required)</mark>\
    Identifier of the party to which the right is delegated.
  * `policyIssuer`\
    **String**. Contained in `delegationPolicyRequest`. <mark style="color:red;">(Required)</mark>\
    Identifier of the delegator, also known as the delegating entity.
  * `target`\
    **Object**. Contained in `delegationPolicyRequest`. <mark style="color:red;">(Required)</mark>\
    MUST for the root level contain an accessSubject. No other elements are allowed. It makes the entire requested delegation policy applicable only to this accessSubject.
    * `accessSubject`\
      **Object**. Contained in `target`. <mark style="color:red;">(Required)</mark>\
      The identifier of the delegate, also known as the entity that receives the delegated rights. It should be a party identifier for M2M cases or a human pseudonym for H2M cases. This would usually hold the same value as policyRequestor.
  * `policySets`\
    **Array of Objects**. Contained in `delegationPolicyRequest`. <mark style="color:red;">(Required)</mark>\
    A container for one or more objects containing policy elements with an indication for further delegation. Note that policySet elements within one delegationPolicyRequest MUST not restrict each other, but rather offer a mechanism to express additional rights. They will be evaluated by the Authorisation Registry in a *permit-override* manner, allowing a *Permit* if only one of the policySet elements evaluates to *Permit*.
    * `maxDelegationDepth`\
      **Integer**. Contained in `policySets`. *Optional*.\
      An optional element that, if present, indicates that further delegation of the rights, conveyed in the policy elements that are part of this PolicySet, is allowed. The value indicates the delegation steps that are allowed after this step in order to evaluate the entire delegation path to *Permit*.
    * `target`

      **Object**. Contained in `policySets`. *Optional.*

      Contains `environment`.

      * `environment`

        **Object**. Contained in `target`. *Optional.*

        Contains `licenses`.

        * `licenses`

          **Array of Strings and Objects**. Contained in `environment`.

          An array which describes which iSHARE licenses apply to this policy set. Please refer to the[licenses-model](https://dev.ishare.eu/licenses-model "mention") for more information about structuring this array.
    * `policies`

      **Array of Objects**. Contained in `policySets`. <mark style="color:red;">(Required)</mark>

      Used to express the actual rights for which evidence is being provided. Note that policies within one policySet object MUST not restrict each other, but rather offer a mechanism to express additional rights. They will be evaluated in a *permit-override* manner, allowing a *Permit* if only one of the policy elements evaluates to *Permit*.

      * `target`\
        **Object**. Contained in `policies`. <mark style="color:red;">(Required)</mark>\
        Describes the target, in terms of resource and action, this request applies. It is also the scope that is permitted through the default rule.
        * `resource`\
          **Object**. Contained in `target`. <mark style="color:red;">(Required)</mark>\
          Contains `type`, `identifiers` and `attributes`.
          * `type`\
            **String**. Contained in `resource`. <mark style="color:red;">(Required)</mark>\
            String which describes the type of resource to which the rules apply.
          * `identifiers`\
            **Array of Strings**. Contained in `resource`. *Optional*.\
            Optional array of strings containing one or more resource identifiers.
          * `attributes`\
            **Array of Strings**. Contained in `resource`. *Optional*.\
            An optional array of attributes of the resources the delegated rights apply to.
        * `actions`\
          **Array of Strings**. Contained in `target`. <mark style="color:red;">(Required)</mark>\
          An array of actions that apply to this policy.
        * `context`\
          **Object**. Contained in `target`. *Optional.*\
          Object containing context information that must be evaluated by the Authorisation Registry before providing Delegation Evidence.
          * `conditions`\
            **Object**. Contained in `context`. *Optional.*\
            Optional conditions which must be evaluated by the Authorisation Registry. For guidance on how to interoperably define conditions, refer to the page about [delegation evidence conditions](https://dev.ishare.eu/authorisation-registry-role/delegation-conditions). The condition structure is the same as the structure when conditions are part of the rules that are provided to the Service Provider/Consumer ([#type-2-evaluate-conditions-by-the-service-provider](https://dev.ishare.eu/delegation-conditions#type-2-evaluate-conditions-by-the-service-provider "mention")). When Delegation Evidence is requested by the Service Provider/Consumer ([#type-1-conditions-evaluated-by-an-authorisation-registry](https://dev.ishare.eu/delegation-conditions#type-1-conditions-evaluated-by-an-authorisation-registry "mention")), it is expected that the context contains key/value pairs on which these conditions must be applied. The following keywords in conditions are reserved:
            * `serviceProviders`: reserved keyword for a condition that contains a list of party identifiers of Service Providers, which are allowed to provide services to the accessSubject.
      * `rules`\
        **Array of Objects**. Contained in `policies`. <mark style="color:red;">(Required)</mark>
        * `effect`\
          **String**. Contained in `rules`. <mark style="color:red;">(Required)</mark>\
          Value must be equal to *Permit* or *Deny*.
        * `conditions`\
          **Object**. Contained in `rules`. *Optional.*\
          Optional conditions which must be evaluated by the Service Provider before the rule applies. The conditions must be provided as-is to the Service Provider. For guidance on how to interoperably define conditions, refer to the page about [delegation evidence conditions](https://dev.ishare.eu/authorisation-registry-role/delegation-conditions) ([#type-2-evaluate-conditions-by-the-service-provider](https://dev.ishare.eu/delegation-conditions#type-2-evaluate-conditions-by-the-service-provider "mention")). The following keywords in conditions are reserved:
          * `serviceProviders`: reserved keyword for a condition that contains a list of party identifiers of Service Providers, which are allowed to provide services to the accessSubject.

### Response

**HTTP status codes**

* **200 OK**

  When the creation of the delegation policy was successful, an OK result should be returned.