# Delegation Policy ## 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":"generic iSHARE API specifications","version":"2.1.1"},"tags":[{"name":"Authorisation Registry","description":"Endpoints that form the Authorisation Registry API specification."}],"servers":[{"description":"iSHARE UAT network base domain","url":"https://isharetest.net"},{"description":"iSHARE TEST network base domain","url":"https://test.ishareworks.nl"}],"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":{"/[v2.1.1]/delegationPolicy":{"post":{"tags":["Authorisation Registry"],"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":"/delegationPolicy","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**.\ OAuth 2.0 authorization based on bearer token. MUST contain “Bearer “ + access token value. How to retrieve the access token can be found at [Access Token Endpoint section](https://gitlab.com/ishare-foundation/cab/developer-portal/-/blob/v2.1.1/all-roles-common-endpoints/access-token-m2m%20\(1\).md). * `Content-Type`\ **String**.\ Defines request body content type. MUST be equal to *application/json*. #### Parameters The body of the request contains [iSHARE Compliant JWT](https://dev.ishare.eu/version-2.1.1/reference/ishare-jwt) delegationPolicyRequestToken. Besides the default attributes (iss, sub, aud, etc.), it contains the following attributes. The model of the delegationPolicyRequestToken [is available on the iSHARE OpenAPI documentation](https://openapi.ishare.eu/?version=2.1#/jwtPayloadDelegationPolicyRequestToken). For convenience the model is also described below. * `delegationPolicyRequest`\ **Object**. Root level.\ Contains information about the delegation policy that is requested to create. * `notBefore`\ **Integer**. Contained in `delegationPolicyRequest`.\ Unix timestamp in UTC indicating the start of validity period of the requested delegation policy. * `notOnOrAfter`\ **Integer**. Contained in `delegationPolicyRequest`.\ Unix timestamp in UTC indicating the end of validity period of the requested delegation policy. * `policyRequestor`\ **String**. Contained in `delegationPolicyRequest`.\ Identifier of the the party to which the right is delegated. * `policyIssuer`\ **String**. Contained in `delegationPolicyRequest`.\ Identifier of the delegator, also know as the delegating entity. * `target`\ **Object**. Contained in `delegationPolicyRequest`.\ 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`.\ Identifier of the delegate, also known as the entity that receives the delegated rights. It should be a party identifier for M2M cases or human pseudonym for H2M cases. This would usually hold the same value as policyRequestor. * `policySets`\ **Array of Objects**. Contained in `delegationPolicyRequest`.\ 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 Authorization 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*.\ 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`. Contains `environment`. * `environment` **Object**. Contained in `target`. Contains `licenses`. * `licenses` **Array of Strings**. Contained in `environment`. Array which describes which iSHARE licenses apply to this policySet. * `policies` **Array of Objects**. Contained in `policySets`. Used to express the actual rights for which evidence is being provided. Note that policies within one policySets 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`.\ Describes the target, in terms of resource and action, this request applies to. It is also the scope that is permitted through the default rule. * `resource`\ **Object**. Contained in `target`.\ Contains `type`, `identifiers` and `attributes`. * `type`\ **String**. Contained in `resource`.\ 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*.\ Optional array of attributes of the resources the delegated rights apply to. * `actions`\ **Array of Strings**. Contained in `target`.\ Array of actions that apply to this policy. * `environment`\ **Object**. Contained in `target`.\ Optional field that contains `serviceProviders`. * `serviceProviders`\ **Array of Strings**. Contained in `environment`. *Optional.*\ Array which lists the iSHARE client ID’s of serviceProviders which are allowed to provide services to the accessSubject as described within this policy. * `rules`\ **Array of Objects**. Contained in `policies`. * `effect`\ **String**. Contained in `rules`.\ Value must be equal to *Permit* or *Deny*. ### Response **HTTP status codes** * **200 OK** When the creation of the delegation policy was succesfull, OK result should be returned.