openapi: 3.2.0 info: title: Authorization API v1.1 Resource Policies API version: 1.1.0 description: 'This specification is intended to describe the Authorization v1.1 APIs ## Roles ### **OrgAdmin** - An entity which has administrative authority over an organization.' servers: - url: Use API Lookup for a base URL security: - Bearer: [] tags: - name: Resource Policies description: Resource Policy Management paths: /resourcePolicies: parameters: - $ref: '#/components/parameters/XCorrelationId' post: tags: - Resource Policies summary: Create a resource policy operationId: createResourcePolicy description: 'Create a resource policy. A resource policy packages resources that are to be made linkable to realms. A resource policy can be homed to a project or created outside of the context of a project. Once a resource home is created for the resource policy, all access to the resource policy would need to be in the context of the project scope. For an unscoped resource policy, the creator is granted "manageResourcePolicy", "addGrant:manageResourcePolicy" access on the resource policy HRN. For a resource policy scoped to a project all members of the home project get the "projectEnabled" action "manageResourcePolicy" access on the resource policy. Access Control: * The calling principal must have **"createResourcePolicy"** action permission in the **"authorization"** service. * The unscoped access to this api is granted via the default authorization policy. * The scoped access to this api is granted via the default "projectEnabled" action for members of the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyRequest' responses: '201': description: Created headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicy' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' get: tags: - Resource Policies summary: Get a list of Resource Policies operationId: getResourcePolicies description: 'Get a list of Resource Policies. If an unscoped access token is used, all resource policies(unscoped and scoped) within the realm of the caller are returned. If a project scoped access token is used, resource policies within the project are returned. Access Control: * The calling principal must have **"readResourcePolicies"** action permission in the **"authorization"** service. * The unscoped access to this api is granted via the default authorization policy. * The scoped access to this api is granted via the default "projectEnabled" action for members of the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] parameters: - $ref: '#/components/parameters/resourceQuery' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/pageToken' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /resourcePolicies/{resourcePolicy}: parameters: - $ref: '#/components/parameters/XCorrelationId' - $ref: '#/components/parameters/resourcePolicy' get: tags: - Resource Policies summary: Get a resource policy operationId: getResourcePolicy description: 'Get details of a Resource Policy. Access Control: * The calling principal must have **"readResourcePolicies"** action permission in the **"authorization"** service. * The unscoped access to this api is granted via the default authorization policy. * The scoped access to this api is granted via the default "projectEnabled" action for members of the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicy' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' delete: tags: - Resource Policies summary: Delete a resource policy operationId: deleteResourcePolicy description: 'Delete a resource policy. Access Control: * The calling principal must have **"manageResourcePolicy"** action permission for the resource **"{resourcePolicy}"** in the **"authorization"** service. * This API works for tokens with or without a project scope.' security: - Bearer: [] responses: '204': description: No Content headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' patch: tags: - Resource Policies summary: Update a resource policy operationId: updateResourcePolicy description: 'Update a resource policy. Access Control: * The calling principal must have **"manageResourcePolicy"** action permission for the resource **"{resourcePolicy}"** in the **"authorization"** service. * This API works for tokens with or without a project scope.' security: - Bearer: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyPatchRequest' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicy' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /resourcePolicies/{resourcePolicy}/resources: parameters: - $ref: '#/components/parameters/XCorrelationId' - $ref: '#/components/parameters/resourcePolicy' post: tags: - Resource Policies summary: Add resources to a resource policy operationId: addResourcesToResourcePolicy description: 'Add the specified list of resources to the Resource Policy with allowedActions in a batch. A maximum of 100 resources may be contained in a single Resource Policy. If a batch would push the ResourcePolicy over-limit, the entire batch fails with an error code indicating available capacity. Note: The allowed actions list must match the Resource''s resource setting allowed actions available for resource policy. By default all "projectLinkingEnabled" are allowed to be added for a resource in a resource policy. Adding a resource to a resource policy enables the ability of the resource to be made linkable to other realms. This batch API response returns a status that can be polled to get information about the batch request. Access Control: * The calling principal must have **"manageResourcePolicy"** action permission for the resource **"{resourcePolicy}"** in the **"authorization"** service. **AND** * According to the resource setting, The calling principal **must either** have permission to take all the "requiredToMakeLinkable" actions against the service inferred via the reserved resource prefix of the resource in the path in the scope of the home project of the resource **or** the Resource''s resource setting is configured to allow anyone within the home realm of the resource to create a resource policy. * When the access token is project scoped, all the resources added to a resource policy must either be homed or referenced in the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyResourcesPayload' responses: '202': description: Accepted headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyResourcesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' get: tags: - Resource Policies summary: Get all resources in a resource policy operationId: getAllResourcesInResourcePolicy description: 'Get a list of resources in a Resource Policy. Access Control: * The calling principal must have **"readResourcePolicies"** action permission in the **"authorization"** service. * The unscoped access to this api is granted via the default authorization policy. * The scoped access to this api is granted via the default "projectEnabled" action for members of the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] parameters: - $ref: '#/components/parameters/Type' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/pageToken' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyResourceList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /resourcePolicies/{resourcePolicy}/resources/status/{statusId}: get: tags: - Resource Policies summary: Get the status of resource policy resources batch addition operationId: getResourcePolicyResourcesStatus parameters: - $ref: '#/components/parameters/XCorrelationId' - $ref: '#/components/parameters/resourcePolicy' - $ref: '#/components/parameters/statusId' description: 'Get the status of resource policy resources batch addition. Access Control: * The calling principal must have **"manageResourcePolicy"** action permission for the resource **"{resourcePolicy}"** in the **"authorization"** service. * The unscoped access to this api is granted via the default authorization policy. * The scoped access to this api is granted via the default "projectEnabled" action for members of the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyResourcePartialSuccessList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /resourcePolicies/{resourcePolicy}/resources/{resource}: parameters: - $ref: '#/components/parameters/XCorrelationId' - $ref: '#/components/parameters/resourcePolicy' - $ref: '#/components/parameters/resource' put: tags: - Resource Policies summary: Add a resource to a resource policy operationId: addResourceToResourcePolicy description: 'Add a resource to the Resource Policy with allowedActions. A maximum of 100 resources may be contained in a single Resource Policy. Note: The allowed actions list must match the Resource''s resource setting allowed actions available for resource policy. By default all "projectLinkingEnabled" are allowed to be added for a resource in a resource policy. Adding a resource to a resource policy enables the ability of the resource to be made linkable to other realms. Access Control: * The calling principal must have **"manageResourcePolicy"** action permission for the resource **"{resourcePolicy}"** in the **"authorization"** service. **AND** * According to the resource setting, The calling principal **must either** have permission to take all the "requiredToMakeLinkable" actions against the service inferred via the reserved resource prefix of the resource in the path in the scope of the home project of the resource **or** the Resource''s resource setting is configured to allow anyone within the home realm of the resource to create a resource policy. * When the access token is project scoped, all the resources added to a resource policy must either be homed or referenced in the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyResource' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyResource' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' get: tags: - Resource Policies summary: Get a resource in a resource policy operationId: getResourceInResourcePolicy description: 'Get resource in a Resource Policy. Access Control: * The calling principal must have **"readResourcePolicies"** action permission in the **"authorization"** service. * The calling principal MUST NOT include a project scope. * The unscoped access to this api is granted via the default authorization policy. * The scoped access to this api is granted via the default "projectEnabled" action for members of the project. * This API works for tokens with or without a project scope.' security: - Bearer: [] responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ResourcePolicyResource' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' delete: tags: - Resource Policies summary: Delete resource from a resource policy operationId: deleteResourceFromResourcePolicy description: 'Delete a resource from a Resource Policy. Also supports comma-separated list of resources in the path for batch delete operation. Access Control: * The calling principal must have **manageResourcePolicy** action permission for the resource **"{resourcePolicy}"** in the **"{authorization}"** service. **OR** * The calling principal **must** have permission to take all the "requiredToMakeLinkable" actions against the service inferred via the reserved resource prefix of the resource in the path in the scope of the home project of the resource. * This API works for tokens with or without a project scope.' security: - Bearer: [] responses: '204': description: No Content headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: ResourcePolicyResourcesResponse: type: object properties: statusId: type: string example: STATUS-5161feb8-5bc4-4e1c-a023-f343d6e5c94f description: 'The status id of the resource policy resources batch request ' href: type: string example: https://account.api.here.com/authorization/v1.1/resourcePolicies/hrn:here:authorization::myrealm:resourcePolicy%2Fmy-policy-000/resources/status/STATUS-5161feb8-5bc4-4e1c-a023-f343d6e5c94f description: 'The status url of the resource policy resources batch request ' ResourcePolicyResourcesPayload: type: object properties: items: type: array description: List of resource policy resources items: $ref: '#/components/schemas/ResourcePolicyResource' Type: type: string example: catalog description: "The type of the resource.\neg - catalog, pipeline, pipeline-template, schema, artifact, flow, flow-pattern, service, resource-policy, \nconnector, routing-customization, search-customization, lastmile, tracking, adminportal\n" allowedActions: type: array items: type: string example: readResource description: 'The list of actions made available for referencing for the resourceType. These actions must be one of the "projectLinkingEnabled" actions of the service inferred via the reserved resource prefix of the resource in the path. ' ErrorDetail: type: object properties: title: type: string description: Error message example: Invalid size value source: type: string description: Reference to JSON path example: $.data.attributes[0].size message: type: string description: Detailed error message example: Size must be between 3 and 64 messageTemplate: type: string description: Optional error template example: validation.constraint.between messagePlaceholders: type: object additionalProperties: {} example: field: size min: 3 max: 64 ErrorResponse: type: object required: - title - status - code - cause - action - errorId properties: title: description: Error title type: string example: Input data failed validation errorId: type: string example: ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1 description: Unique id for the error. This is searchable from HERE Account logs. status: description: HTTP Status Code type: integer example: 400 code: description: Service specific error code type: string example: E202101 cause: description: The cause of the error type: string example: The input data in question does not meet validation rules action: description: Actionable instructions for the API consumer type: string example: Correct input data and retry request correlationId: description: Trace ID associated with this request, for future use type: string example: 4199533b-6290-41db-8d79-edf4f4019a74 details: type: array description: Collection of error details items: $ref: '#/components/schemas/ErrorDetail' subresources: type: array maxItems: 10 items: type: string maxLength: 24 example: - usa-il-chicago - deu description: 'The list of associated subresource identifiers. ' ResourcePolicyList: type: object allOf: - $ref: '#/components/schemas/PageWithToken' - type: object properties: items: type: array items: $ref: '#/components/schemas/ResourcePolicy' description: List of resource policies in the realm ResourcePolicyResourceList: type: object allOf: - $ref: '#/components/schemas/PageWithToken' - type: object properties: items: type: array description: List of resource policy resources items: $ref: '#/components/schemas/ResourcePolicyResource' PageWithToken: type: object required: - limit - total - items properties: limit: type: integer example: 1 description: Maximum number of items to return. pageToken: type: string example: KuMvTQrdHVVKuMDDdcIvTQrdci1FWdcIHVVci1FW description: The cursor for pagination. Present only if there is an additional page of data to view. total: type: integer example: 1 description: Total number of items matching the search criteria. ResourcePolicyResource: type: object properties: resource: type: string example: hrn:here:data::myrealm:my-catalog description: 'The hrn of the resource ' allowedActions: $ref: '#/components/schemas/allowedActions' subresources: $ref: '#/components/schemas/subresources' ResourcePolicyRequest: type: object required: - id - name properties: id: type: string example: my-vanity-id description: 'The id of the resource policy. The ID must comply to the regex - (^[a-zA-Z0-9][a-zA-Z0-9\-:]{2,61}[a-zA-Z0-9]$) ' name: type: string example: My resource policy description: 'The name of the resource policy ' description: type: string example: This is my resource policy description: 'The description of the resource policy ' ResourcePolicy: type: object properties: hrn: type: string example: hrn:here:authorization::myrealm:resourcePolicy/my-policy-000 description: 'The hrn of the resource policy ' id: type: string example: my-vanity-id description: 'The id of the resource policy ' name: type: string example: My resource policy description: 'The name of the resource policy ' description: type: string example: This is my resource policy description: 'The description of the resource policy ' ResourcePolicyResourcePartialSuccessList: type: object properties: status: type: string enum: - pending - inProgress - failure - success - partialSuccess example: partialSuccess description: 'The status of the batch call for adding resources to a resource policy ' resource: type: object properties: href: type: string example: https://account.api.here.com/authorization/v1.1/resourcePolicies/hrn:here:authorization::myrealm:resourcePolicy%2Fmy-policy-000/resources description: 'Get the resources in the resource policy ' items: type: array description: List of resource policy resources items: type: object properties: resource: type: string example: hrn:here:data::myrealm:my-catalog description: 'The hrn of the resource ' status: type: integer example: 403 description: 'Status code for the resource add request ' code: description: Service specific error code type: string example: EXXXYYY ResourcePolicyPatchRequest: type: object properties: name: type: string example: My resource policy description: 'The name of the resource policy ' description: type: string example: This is my resource policy description: 'The description of the resource policy ' parameters: resource: in: path name: resource schema: type: string required: true description: 'The hrn that identifies the resource. ' example: hrn:here:data::myrealm:my-catalog resourceQuery: in: query name: resource schema: type: string required: false description: 'The hrn that identifies the resource. ' example: hrn:here:data::myrealm:my-catalog limit: in: query name: limit required: false description: Number of records to return. Default is 100 records. Maximum is 100 records. schema: type: integer minimum: 0 maximum: 100 default: 100 XCorrelationId: in: header name: X-Correlation-ID schema: type: string required: false description: 'Correlates HTTP requests between a client and server. If not present in the incoming request, it will be generated. ' Type: in: query name: type required: false description: The type of the resource. schema: $ref: '#/components/schemas/Type' pageToken: name: pageToken in: query description: The cursor for pagination. Present only if there is an additional page of data to view. schema: type: string example: KuMvTQrdHVVKuMDDdcIvTQrdci1FWdcIHVVci1FW statusId: in: path name: statusId required: true description: 'The status id of the resource policy resources batch request ' schema: type: string example: STATUS-5161feb8-5bc4-4e1c-a023-f343d6e5c94f resourcePolicy: in: path name: resourcePolicy required: true description: The HRN of the resource policy schema: type: string example: hrn:here:authorization::myrealm:resourcePolicy/my-policy-0000 headers: XCorrelationId: schema: type: string required: false description: 'Correlates HTTP requests between a client and server. If not present in the incoming request, it will be generated. ' responses: Forbidden: description: You do not have permission to perform this action headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Access is denied due to invalid credentials headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' BadRequest: description: Invalid input provided, see error response for details headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT description: Bearer Access Token issued to either the User or Client. externalDocs: description: The developer guide and related API references are available here. url: https://www.here.com/docs/category/identity-and-access-management