swagger: '2.0' info: title: Resource Access Management API description: | The Resource Access Management API provides a means to define and manage access policies to achieve fine-grained access of various business resources. Also, it provides ability to organize group of resources which can be a part of policies. ## Limitations - The number of existing policies is limited per owner/tenant. - The number of existing subjects/rules is limited per policy. - The number of existing actions/resources is limited per rule. - 'Default_Policy_tenant' represents the system generated policy name for the given tenant/owner. No other operation except activation/de-activation is allowed for such a policy. ## Notes - If the request URL has trailing slash character "/", then the API would respond with 404 error. So API callers are advised not to use trailing slash in URLs to avoid broken link. For example, "/policies/" is not a well-formed URL, instead, please use "/policies". - In the examples below, while specifying subjects or resources, the correct region code should be provided. - "eu1" denotes Public Cloud "Europe 1" region. For example, mdsp:core:identitymanagement:eu1:tenantA:user:dummy@example.com - "gbl" denotes Private Cloud deployment region. For example, mdsp:core:identitymanagement:gbl:tenantA:user:dummy@example.com version: '3.2.0' x-visibility: external basePath: /api/resourceaccessmanagement/v3 schemes: - https produces: - application/json consumes: - application/json tags: - name: Policy Management Endpoints description: API for managing policies - name: Resource Group Endpoints description: API for managing resource groups paths: /policies: get: tags: - Policy Management Endpoints operationId: listPolicies summary: List all policies. description: List all policies of a tenant. Filter is supported on following fields- id, owner, name, active, subjects, resources, createdBy and lastModifiedBy. parameters: - name: size in: query description: | Specifies the number of elements in a page. type: integer format: int32 minimum: 1 maximum: 100 default: 10 - name: page in: query description: | Specifies the requested page index. type: integer format: int32 minimum: 0 default: 0 - name: filter in: query type: string description: Specifies the additional filtering criteria responses: '200': description: OK schema: $ref: '#/definitions/PolicyList' '401': description: User is not authenticated '403': description: User is not authorized for request '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.p.r' post: tags: - Policy Management Endpoints operationId: createPolicy summary: Create a policy. description: Create a new policy with the provided content. parameters: - in: body name: policy description: | The policy object to be created. Note: The policy object sent in the request might contain further properties (e.g. as specified in the response object, but also beyond), yet those will be ignored. required: true schema: $ref: '#/definitions/PolicyRequest' responses: '201': description: Created headers: ETag: description: Resource version for optimistic locking type: number schema: $ref: '#/definitions/PolicyResponse' '400': description: | Bad Request. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- providedNameInValid  | Name should be max 100 chars and [a-zA-Z0-9_-] maxNumberOfPoliciesInQuotaExceeded  | Maximum number of policies exceeded for given owner subjectInvalid  | Subject is in invalid format schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '409': description: | Conflict. Possible errors: Code Suffix | Message ------------- |------------- policyUniquenessConditionFailed  | The policy with same name already exists. Please try with another name schema: $ref: '#/definitions/MdspErrors' '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.p.c' /policies/{id}: get: tags: - Policy Management Endpoints operationId: getPolicy summary: Get a policy description: Retrieves a specific policy of the current tenant. parameters: - name: id in: path description: Id of the policy to retrieve. required: true type: string responses: '200': description: OK headers: ETag: description: Resource version for optimistic locking type: number schema: $ref: '#/definitions/PolicyResponse' '404': description: | Not found. Possible errors: Code Suffix | Message (parametrized) ------------- |------------- policyNotFound  | Policy with given id not found schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.p.r' put: tags: - Policy Management Endpoints operationId: updatePolicy summary: Update a policy. description: Update a policy. Admin user can re-activate 'Default_Policy' only if no other active policy exists. parameters: - name: id in: path description: Id of policy to update required: true type: string - in: body name: policy description: The updated policy object. required: true schema: $ref: '#/definitions/PolicyRequest' - name: If-Match in: header description: Last known version of the policy to facilitate optimistic locking. required: true type: string responses: '200': description: OK headers: ETag: description: Resource version for optimistic locking type: number schema: $ref: '#/definitions/PolicyResponse' '400': description: | Bad Request. Possible errors: Code Suffix | Message ------------- |------------- maxNumberOfRulesExceeeded  | Maximum number of rules exceeded maxNumberOfActionsExceeeded  | Maximum number of actions exceeded defaultPolicyValidation  | 'Default_Policy' can only be re-activated if no other active policy exists schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '404': description: | Not found. Possible errors: Code Suffix | Message (parametrized) ------------- |------------- policyNotFound  | Policy with given id not found schema: $ref: '#/definitions/MdspErrors' '412': description: Precondition Failed schema: $ref: '#/definitions/MdspErrors' '428': description: Precondition Required schema: $ref: '#/definitions/MdspErrors' '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.p.u' delete: tags: - Policy Management Endpoints operationId: deletePolicy summary: Delete a policy. description: Delete a policy with given id. 'Default_Policy' cannot be deleted. parameters: - name: id in: path description: Id of the policy to be deleted. required: true type: string responses: '204': description: No Content '404': description: | Not found. Possible errors: Code Suffix | Message (parametrized) ------------- |------------- policyNotFound  | Policy with given id not found schema: $ref: '#/definitions/MdspErrors' '400': description: | Bad Request. Possible errors: Code Suffix | Message (parametrized) ------------- |------------- defaultPolicyValidation  | Given id is of Default_Policy which cannot be deleted schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.p.d' /resourceGroups: get: tags: - Resource Group Endpoints operationId: listResourceGroups summary: List all resource groups. description: List all resource groups of a tenant. Filter is supported on following fields- id, owner, displayName, groupName, members, createdBy and lastModifiedBy. parameters: - name: size in: query description: | Specifies the number of elements in a page. type: integer format: int32 minimum: 1 maximum: 100 default: 10 - name: page in: query description: | Specifies the requested page index. type: integer format: int32 minimum: 0 default: 0 - name: filter in: query type: string description: Specifies the additional filtering criteria responses: '200': description: OK schema: $ref: '#/definitions/ResourceGroupList' '401': description: User is not authenticated '403': description: User is not authorized for request '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.rg.r' post: tags: - Resource Group Endpoints operationId: createResourceGroup summary: Create a resource group. description: Create a new resource group with the provided content. parameters: - in: body name: resourceGroup description: | The resource group object to be created. Note: The resource group object sent in the request might contain further properties (e.g. as specified in the response object, but also beyond), yet those will be ignored. required: true schema: $ref: '#/definitions/ResourceGroupRequest' responses: '201': description: Created headers: ETag: description: Resource version for optimistic locking type: number schema: $ref: '#/definitions/ResourceGroupResponse' '400': description: | Bad Request. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- providedDisplayNameInValid  | Name should be max 100 chars and [a-zA-Z0-9_-] maxNumberOfMembersExceeded  | Maximum number of members exceeded for given resource group memberInvalid  | Member is in invalid format maxNumberOfGroupsExceeded  | Maximum number of resource groups exceeded for given owner schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '409': description: | Conflict. Possible errors: Code Suffix | Message ------------- |------------- displayNameUniquenessConditionFailed  | The resource group with given displayName already exists. Please try with another displayName schema: $ref: '#/definitions/MdspErrors' '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.rg.c' /resourceGroups/{id}: get: tags: - Resource Group Endpoints operationId: getResourceGroup summary: Get a resource group description: Retrieves a specific resource group of the current tenant. parameters: - name: id in: path description: Id of the resource group to retrieve. required: true type: string responses: '200': description: OK headers: ETag: description: Resource version for optimistic locking type: number schema: $ref: '#/definitions/ResourceGroupResponse' '404': description: | Not found. Possible errors: Code Suffix | Message (parametrized) ------------- |------------- resourceGroupNotFound  | Resource group with given id not found schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.rg.u' put: tags: - Resource Group Endpoints operationId: updateResourceGroup summary: Update a resource group. description: Update a resource group. parameters: - name: id in: path description: Id of resource group to update required: true type: string - in: body name: resourceGroup description: The updated resource group object. required: true schema: $ref: '#/definitions/ResourceGroupRequest' - name: If-Match in: header description: Last known version of the resource group to facilitate optimistic locking. required: true type: string responses: '200': description: OK headers: ETag: description: Resource version for optimistic locking type: number schema: $ref: '#/definitions/ResourceGroupResponse' '400': description: | Bad Request. Possible errors: Code Suffix | Message ------------- |------------- maxNumberOfMembersExceeded  | Maximum number of members exceeded for given resource group schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '404': description: | Not found. Possible errors: Code Suffix | Message (parametrized) ------------- |------------- resourceGroupNotFound  | Resource group with given id not found schema: $ref: '#/definitions/MdspErrors' '412': description: Precondition Failed schema: $ref: '#/definitions/MdspErrors' '428': description: Precondition Required schema: $ref: '#/definitions/MdspErrors' '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.p.u' delete: tags: - Resource Group Endpoints operationId: deleteResourceGroup summary: Delete a resource group. description: Delete a resource group with given id. parameters: - name: id in: path description: Id of the resource group to be deleted. required: true type: string responses: '204': description: No Content '404': description: | Not found. Possible errors: Code Suffix | Message (parametrized) ------------- |------------- resourceGroupNotFound  | Resource group with given id not found schema: $ref: '#/definitions/MdspErrors' '401': description: User is not authenticated '403': description: User is not authorized for request '429': description: | Too Many Requests. Possible errors: Code Suffix | Message (parameterized) ------------- |------------- tooManyRequests  | API rate limit exceeded schema: $ref: '#/definitions/MdspErrors' security: - ram: - 'ram.rg.d' definitions: ETag: type: integer description: An identifier for a specific version of a resource. example: 1 MdspErrors: type: object properties: errors: type: array items: $ref: '#/definitions/MdspError' MdspError: description: A descriptor for error responses. allOf: - $ref: '#/definitions/MdspApiError' - type: object properties: logref: type: string description: "Logging correlation ID for debugging purposes." example: "0bff7e7a-cd25-4576-9908-4180ef086174" MdspApiError: type: object description: A descriptor for errors that are integral parts of resources. properties: code: type: string description: "Unique error code. Every code is bound to one (parametrized) message." format: "mdsp.core.resourceaccessmanagement." example: "mdsp.core.resourceaccessmanagement.exampleCode" message: type: string description: "Human readable error message in English." example: "Example error message with parameter value 100" messageParameters: type: array description: | In case an error message is parametrized, the parameter names and values are returned for, e.g., localization purposes. The parametrized error messages are defined at the operation error response descriptions in this API specification. Parameters are denoted by named placeholders '{\}' in the message specifications. At runtime, returned message placeholders are substituted by actual parameter values. items: type: object description: "Message parameter" properties: name: type: string description: "Name of message parameter as specified in parametrized error message." value: type: string description: "Value of message parameter as substituted in returned error message." example: - { "name": "exampleParameterName", "value": "100" } PolicyList: type: object properties: policies: type: array items: $ref: '#/definitions/PolicyListResponse' page: $ref: '#/definitions/Page' ResourceGroupList: type: object properties: resourceGroups: type: array items: $ref: '#/definitions/ResourceGroupResponse' page: $ref: '#/definitions/Page' Page: type: object properties: size: type: integer example: 10 totalElements: type: integer example: 1 totalPages: type: integer example: 1 number: type: integer example: 0 PolicyRequest: description: Policy represents the configuration of a single policy. properties: name: description: "Name is a client defined identifier. It must be unique within a tenant (owner). Maximum 100 characters on [a-zA-Z0-9_-]. 'Default_Policy' is a case in-sensitive reserved word. No Policy name can contain 'Default_Policy' word in any combination." type: string example: "EventPolicy" description: description: "Description of the policy. This is an optional property with a limit of 500 characters." type: string example: "This policy defines the access rules for a technician." maxLength: 500 active: description: "Indicating whether the policy should be active or not, i.e., active policies must be enforced; non-active policies must not be enforced." type: boolean default: true example: true subjects: type: array items: $ref: "#/definitions/subjects" rules: type: array items: type: object properties: name: description: "Rule Name is a case-insensitive, client defined identifier. It must be unique within a policy. Populated automatically, if not set by client/user. Maximum 100 characters on [a-zA-Z0-9_-]." type: string example: Rule1 actions: type: array items: $ref: "#/definitions/ruleAction" resources: type: array items: $ref: "#/definitions/ruleResource" propagationDepth: type: integer enum: [0, 1, -1] default: -1 description: To support resource hierarchy, this parameter is introduced at the Rule level. 0 - No propagation. Exact resources specified in the rule are included in the applicability of that rule. No hierarchy support for the included resources. 1 - Direct children Only. The exact resource mentioned, and its direct children are included in the applicability of the rule. -1 - Unlimited depth. All the resources (direct children and their descendants till leaf node) that are below the specified resources in that rule are included in the applicability of that rule. required: - actions - resources required: - name - subjects - rules type: object PolicyResponse: description: Policy represents the configuration of a single Policy. properties: owner: description: "The name of the tenant of the user who created this object. Populated by the system. Client provided values of this field will be ignored." type: string example: "tenantA" id: description: "Id is the unique identifier for this object. It is generated by the server on successful creation of a rule. It is not allowed to change on PUT operations." type: string example: "94411f5a-cf07-4281-b7f3-ce39ca53fe00" name: description: "Name is a client defined identifier. It must be unique within a tenant (owner). Maximum 100 characters on [a-zA-Z0-9_-]." type: string example: "EventPolicy" description: description: "Description of the policy. This is an optional property with a limit of 500 characters." type: string example: "This policy defines the access rules for a technician." maxLength: 500 active: description: "Indicating whether the policy should be active or not, i.e., active policies must be enforced; non-active policies must not be enforced." type: boolean example: true subjects: type: array items: $ref: "#/definitions/subjects" rules: type: array items: type: object properties: name: description: "Rule Name is a case-insensitive, client defined identifier. It must be unique within a policy. Populated automatically, if not set by client/user. Maximum 100 characters on [a-zA-Z0-9_-]." type: string example: Rule1 actions: type: array items: $ref: "#/definitions/ruleAction" resources: type: array items: $ref: "#/definitions/ruleResource" propagationDepth: type: integer enum: [0, 1, -1] default: -1 description: To support resource hierarchy, this parameter is introduced at the Rule level. 0 - No propagation. Exact resources specified in the rule are included in the applicability of that rule. No hierarchy support for the included resources. 1 - Direct children Only. The exact resource mentioned, and its direct children are included in the applicability of the rule. -1 - Unlimited depth. All the resources (direct children and their descendants till leaf node) that are below the specified resources in that rule are included in the applicability of that rule. required: - actions - resources createdAt: description: "Indicates the date and time this policy was created. Conforms to RFC 3339." format: date-time type: string example: "2019-10-12T07:20:50.52Z" lastModifiedAt: description: "Indicates the date and time this policy was last modified. Conforms to RFC 3339." format: date-time type: string example: "2019-10-12T07:20:50.52Z" createdBy: description: "Indicates the Resource Name who created this policy." type: string example: "mdsp:core:identitymanagement:eu1:core:client:client1234" lastModifiedBy: description: "Indicates the Resource Name who last modified this policy." type: string example: "mdsp:core:identitymanagement:eu1:core:client:client1234" eTag: $ref: '#/definitions/ETag' required: - owner - id - name - active - subjects - rules - createdAt - lastModifiedAt - createdBy - lastModifiedBy - eTag PolicyListResponse: description: Policy object representation in context of a list request. properties: owner: description: "Owner is name of tenant who owns the policy." type: string example: "tenantA" id: description: "Id is the unique identifier for this object. It is generated by the server on successful creation of a rule. It is not allowed to change on PUT operations." type: string example: "94411f5a-cf07-4281-b7f3-ce39ca53fe00" name: description: "Name is a client defined identifier. It must be unique within a tenant (owner). Maximum 100 characters on [a-zA-Z0-9_-]." type: string example: "EventPolicy" description: description: "Description of the policy. This is an optional property with a limit of 500 characters." type: string example: "This policy defines the access rules for a technician." maxLength: 500 active: description: "Indicates whether given plicy is active or inactive." type: boolean example: true subjects: type: array items: $ref: "#/definitions/subjects" rules: type: array items: type: object properties: name: description: "Rule Name is a case-insensitive, client defined identifier. It must be unique within a policy. Populated automatically, if not set by client/user. Maximum 100 characters on [a-zA-Z0-9_-]." type: string example: Rule1 actions: type: array items: $ref: "#/definitions/ruleAction" resources: type: array items: $ref: "#/definitions/ruleResource" propagationDepth: type: integer enum: [0, 1, -1] default: -1 description: To support resource hierarchy, this parameter is introduced at the Rule level. 0 - No propagation. Exact resources specified in the rule are included in the applicability of that rule. No hierarchy support for the included resources. 1 - Direct children Only. The exact resource mentioned, and its direct children are included in the applicability of the rule. -1 - Unlimited depth. All the resources (direct children and their descendants till leaf node) that are below the specified resources in that rule are included in the applicability of that rule. required: - actions - resources createdAt: description: "Indicates the date and time this policy was created. Conforms to RFC 3339." format: date-time type: string example: "2019-10-12T07:20:50.52Z" lastModifiedAt: description: "Indicates the date and time this policy was last modified. Conforms to RFC 3339." format: date-time type: string example: "2019-10-12T07:20:50.52Z" createdBy: description: "Indicates the Resource Name who created this policy." type: string example: "mdsp:core:identitymanagement:eu1:core:client:client1234" lastModifiedBy: description: "Indicates the Resource Name who last modified this policy." type: string example: "mdsp:core:identitymanagement:eu1:core:client:client1234" eTag: $ref: '#/definitions/ETag' required: - owner - id - name - active - subjects - rules - createdAt - lastModifiedAt - createdBy - lastModifiedBy - eTag ResourceGroupResponse: description: Resource Group represents a bundle of different types of resources in scope of Resource Access Management. properties: owner: description: "The name of the tenant of the user who created this object. Populated by the system. Client provided values of this field will be ignored." type: string example: "tenantA" id: description: "Id is the unique identifier for this object. It is generated by the server on successful creation of a resource group. It is not allowed to change on PUT operations." type: string example: "ec2c337c9b0045f99e0a2bd90aefb82f" displayName: description: "displayName is a client defined, case-insensitive identifier. It must be unique within a tenant (owner). Maximum 100 characters on [a-zA-Z0-9_-]. Single spsce allowed between words." type: string example: "Printers on first floor" groupName: description: "groupName is a system generated name. Cannot be updated." type: string example: "mdsp:core:resourceaccessmanagement:eu1:tenantA:resourceGroup:ec2c337c9b0045f99e0a2bd90aefb82f" description: description: "Description of the resource group. This is an optional property with a limit of 500 characters." type: string example: "This resource group contains all printers on first floor of building." maxLength: 500 members: type: array items: $ref: "#/definitions/memberObject" createdAt: description: "Indicates the date and time this policy was created. Conforms to RFC 3339." format: date-time type: string example: "2019-10-12T07:20:50.52Z" lastModifiedAt: description: "Indicates the date and time this policy was last modified. Conforms to RFC 3339." format: date-time type: string example: "2019-10-12T07:20:50.52Z" createdBy: description: "Indicates the Resource Name who created this policy." type: string example: "mdsp:core:identitymanagement:eu1:tenantA:user:dummy@example.com" lastModifiedBy: description: "Indicates the Resource Name who last modified this policy." type: string example: "mdsp:core:identitymanagement:eu1:tenantA:user:dummy@example.com" eTag: $ref: '#/definitions/ETag' required: - owner - id - displayName - groupName - createdAt - lastModifiedAt - createdBy - lastModifiedBy - eTag ResourceGroupRequest: description: Resource Group represents a bundle of different types of resources in scope of Resource Access Management. properties: displayName: description: "displayName is a client defined, case-insensitive identifier. It must be unique within a tenant (owner). Maximum 100 characters on [a-zA-Z0-9_-]. Single spsce allowed between words." type: string example: "Printers on first floor" description: description: "Description of the resource group. This is an optional property with a limit of 500 characters." type: string example: "This resource group contains all printers on first floor of building." maxLength: 500 members: type: array items: $ref: "#/definitions/memberObject" required: - displayName subjects: description: Resource path identifying of a subject or a group of subjects a policy is to be applied to. type: string maxLength: 300 example: "mdsp:core:identitymanagement:eu1:tenantA:user:test@example.com" ruleResource: description: Resource path describing the resource that a rule is to be applied to. type: string maxLength: 300 example: "mdsp:core:assetmanagement:eu1:tenantA:asset:dfb0d2961a224a259c44d8c3f76204fe" ruleAction: description: Identifier describing the action that a rule is to be applied to. type: string maxLength: 255 example: "mdsp:core:assetmanagement:asset:read" memberObject: description: A resource which can be part/member of a resource group. Maximum 100 resources/members are allowed within a reource group. Resource group can have heterogeneous resources (eg. asset, prefix). type: string maxLength: 300 example: "mdsp:core:assetmanagement:eu1:tenantA:asset:dfb0d2961a224a259c44d8c3f76204fe" securityDefinitions: ram: type: oauth2 flow: accessCode authorizationUrl: 'https://UAA_DOMAIN/oauth/authorize' tokenUrl: 'https://UAA_DOMAIN/oauth/token' scopes: ram.p.c: 'create a policy' ram.p.r: 'read a policy or list all policies' ram.p.u: 'update a policy' ram.p.d: 'delete a policy' ram.rg.r: 'read a resource group or list all resource groups' ram.rg.c: 'create a resource group' ram.rg.u: 'update a resource group' ram.rg.d: 'delete a resource group'