openapi: 3.2.0
info:
  title: Attribute Based Access Control Roles API
  description: "Access Control in Adobe Experience Platform allows organization administrators to assign roles and permissions for various Platform capabilities. The Access Control API provides a public endpoint to retrieve effective policies for a user on given resources within a specified sandbox. All other access control capabilities are provided through the [Adobe Admin Console](https://adminconsole.adobe.com).\n- Related documentation:\n    - [Access Control documentation](https://adobe.com/go/access-control-overview-en)\n\n- Visualize API calls with Postman (a free, third-party software):\n    - [Access Control API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Access%20Control%20API.postman_collection.json)\n    - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n    - [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n- API paths:\n    - PLATFORM Gateway URL: https://<span>platform.adobe.io\n    - Base path for this API: /data/foundation/access-control\n    - Example of a complete path for making a call to \"/acl/effective-policies\": https://<span>platform.adobe.io/data/foundation/access-control/acl/effective-policies\n\n- Required headers:\n    - All service calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n    - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n    - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/foundation/access-control
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Attribute Based Access Control Roles
  description: Attribute based access control roles define the access that an administrator, a specialist, or an end-user has to resources in your organization. More information about using this set of endpoints can be found in the [roles endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/access-control/abac/abac-api/roles.html).
paths:
  /administration/roles:
    get:
      tags:
      - Attribute Based Access Control Roles
      summary: List all existing roles
      operationId: listExistingRoles
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rolesResponse'
    post:
      tags:
      - Attribute Based Access Control Roles
      summary: Create a new role
      operationId: createRole
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      requestBody:
        description: The request body for creating a role.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createNewRoleRequestBody'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/roles'
  /administration/roles/{ROLE_ID}:
    get:
      tags:
      - Attribute Based Access Control Roles
      summary: Retrieve a role
      operationId: retrieveRole
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - name: ROLE_ID
        in: path
        description: The ID of the role you want to retrieve.
        required: true
        schema:
          type: string
          example: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/roles'
    patch:
      tags:
      - Attribute Based Access Control Roles
      summary: Update role properties
      operationId: updateRole
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - name: ROLE_ID
        in: path
        description: The ID of the role you want to update.
        required: true
        schema:
          type: string
          example: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
      requestBody:
        description: The request body for updating a role.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rolePatchOperation'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/roles'
    put:
      tags:
      - Attribute Based Access Control Roles
      summary: Update a role by role ID
      operationId: updateRoleByRoleId
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - name: ROLE_ID
        in: path
        description: The ID of the role you want to update.
        required: true
        schema:
          type: string
          example: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
      requestBody:
        description: The request body for updating a role using the role ID.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/roleUpdateById'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/roles'
    delete:
      tags:
      - Attribute Based Access Control Roles
      summary: Delete a role
      operationId: deleteRole
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - name: ROLE_ID
        in: path
        description: The ID of the role you want to delete.
        required: true
        schema:
          type: string
          example: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
      responses:
        204:
          description: A successful response returns HTTP status 204 (No Content) and a blank body.
          content:
            application/json:
              schema:
                type: object
  /administration/roles/{ROLE_ID}/subjects:
    get:
      tags:
      - Attribute Based Access Control Roles
      summary: Retrieve subjects
      operationId: retrieveSubjects
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - name: ROLE_ID
        in: path
        description: The ID of the role you want to retrieve.
        required: true
        schema:
          type: string
          example: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retrieveSubjects'
    patch:
      tags:
      - Attribute Based Access Control Roles
      summary: Update subjects by role Id
      operationId: updateSubjects
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - name: ROLE_ID
        in: path
        description: The ID of the role containing the subjects you want to update.
        required: true
        schema:
          type: string
          example: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
      requestBody:
        description: Update the subjects associated with a given a role ID.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subjectPatchOperation'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subjectsByRoleId'
components:
  schemas:
    rolesResponse:
      type: object
      properties:
        items:
          type: array
          description: A list of roles belonging to your organization.
          items:
            $ref: '#/components/schemas/roles'
        _page:
          type: object
          description: An object that shows what page the list is on.
          properties:
            orderBy:
              type: string
              example: -createdAt
              description: The field by which the results are ordered.
            start:
              type: integer
              example: 0
              description: The index of the first item in the response.
            count:
              type: integer
              example: 20
              description: The number of results returned per page.
            next:
              type: integer
              example: 28375
              description: The index of the first item in the next page of results.
            properties:
              type: array
              items:
                type: string
              description: The list of properties included in the response.
        _links:
          type: object
          description: Contains the URL for the currently displayed response page.
          properties:
            next:
              type: object
              properties:
                href:
                  type: string
                  example: /roles?limit={limit}&start={start}&orderBy={orderBy}&property={property}
                  description: The URL for the currently displayed response page.
                templated:
                  type: boolean
                  description: Indicates if the sibling `href` property is a template.
            page:
              type: object
              properties:
                href:
                  type: string
                  example: /roles?start=1725286843752&orderBy=-createdAt&limit=20
                  description: The URL for the currently displayed response page.
                templated:
                  type: boolean
                  description: Indicates if the sibling `href` property is a template.
            self:
              type: object
              properties:
                href:
                  type: string
                  example: /roles
                  description: The URL for the currently displayed response page.
                templated:
                  type: boolean
                  example: false
                  description: Indicates if the sibling `href` property is a template.
                type:
                  type: string
                  example: null
                  description: The type of the link.
                method:
                  type: string
                  example: null
                  description: The HTTP method used for the link.
    subjectPatchOperation:
      required:
      - op
      - path
      - value
      type: object
      properties:
        op:
          type: string
          description: The operation call used to define the action needed to update the role. Operations include add, replace, and remove.
          example: add
          enum:
          - add
          - replace
          - remove
        path:
          type: string
          description: The path of the parameter to be updated.
          example: /user
        value:
          type: string
          description: The new value you want to update your parameter with.
          example: example@AdobeID
      description: Patch operation.
    subjectsByRoleId:
      type: object
      properties:
        subjects:
          type: array
          description: A list of subjects associated with the queried role ID, including the corresponding subject ID and subject type.
          items:
            $ref: '#/components/schemas/subjectsForRole'
        _page:
          type: object
          description: An object that shows what page the list is on.
          properties:
            limit:
              type: integer
              example: 1
              description: Limit the response to a specific number of objects. This must be a positive number. For example, `limit=10`.
            count:
              type: integer
              example: 1
              description: The number of results returned per page.
        _links:
          type: object
          description: Contains the URL for the currently displayed response page.
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  example: https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects
                  description: The URL for the currently displayed response page.
                templated:
                  type: boolean
                  example: true
                  description: Indicates if the `href` property is a template.
            page:
              type: object
              properties:
                href:
                  type: string
                  example: https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}
                  description: The URL for the currently displayed response page.
                templated:
                  type: boolean
                  example: true
                  description: Indicates if the `href` property is a template.
    rolePatchOperation:
      required:
      - op
      - path
      - value
      type: object
      properties:
        op:
          type: string
          description: The operation call used to define the action needed to update the role. Operations include add, replace, and remove.
          example: add
          enum:
          - add
          - replace
          - remove
        path:
          type: string
          description: The path of the parameter to be updated.
          example: /description
        value:
          type: string
          description: The new value you want to update your parameter with.
          example: Role for administrator type of responsibilities and access.
      description: Patch operation.
    subjects:
      type: object
      properties:
        roleId:
          type: string
          description: The ID of the role.
        subjectType:
          type: string
          description: The type of queried subject.
        subjectId:
          type: string
          description: The ID that corresponds with the queried subject.
      example:
      - roleId: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
        subjectType: user
        subjectId: 03Z07HFQCCUF3TUHAX274206@AdobeID
      - roleId: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
        subjectType: user
        subjectId: PIRJ7WE5T3QT9Z4TCLVH86DE@AdobeID
      - roleId: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
        subjectType: user
        subjectId: WHPWE00MC26SHZ7AKBFG403D@AdobeID
    createNewRoleRequestBody:
      type: object
      properties:
        name:
          type: string
          example: People who ordered in the last 30 days
          description: The name of your role.
        description:
          type: string
          example: Role for administrator type of responsibilities and access.
          description: A descriptive value that you can include to provide more information on your role.
        roleType:
          type: string
          example: user-defined
          enum:
          - user-defined
          - system-defined
          description: The designated type of the role. The possible values for role type are user-defined and system-defined.
    retrieveSubjects:
      type: object
      properties:
        items:
          type: array
          description: A list ofsubjects associated with the queried role ID, including the corresponding subject ID and subject type.
          items:
            $ref: '#/components/schemas/subjects'
        _page:
          type: object
          description: An object that shows what page the list is on.
          properties:
            limit:
              type: integer
              example: 1
              description: Limit the response to a specific number of objects. This must be a positive number. For example, `limit=10`.
            count:
              type: integer
              example: 3
              description: The number of results returned per page.
        _links:
          type: object
          description: Contains the URL for the currently displayed response page.
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  example: https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects
                  description: The URL for the currently displayed response page.
                templated:
                  type: boolean
                  example: true
                  description: Indicates if the `href` property is a template.
            page:
              type: object
              properties:
                href:
                  type: string
                  example: https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}
                  description: The URL for the currently displayed response page.
                templated:
                  type: boolean
                  example: true
                  description: Indicates if the `href` property is a template.
    roleUpdateById:
      required:
      - name
      - description
      - roleType
      type: object
      properties:
        name:
          type: string
          description: The updated name of a role.
          example: Administrator Role
        description:
          type: string
          description: The updated description of a role.
          example: Role for administrator type of responsibilities and access.
        roleType:
          type: string
          description: The designated type of the role. The possible values for role type are user-defined and system-defined.
          example: user-defined
          enum:
          - user-defined
          - system-defined
      description: Put operation.
    roles:
      type: object
      properties:
        id:
          type: string
          example: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
          description: The ID of the role.
        recordType:
          type: string
          example: role
          description: The record type of the role.
        imsOrgID:
          type: string
          example: 5555467B5D8013E50A494220@AdobeOrg
          description: The organization where the queried role is accessible.
        createdAt:
          type: integer
          example: 1648153201825
          description: A timestamp to date the creation of the role.
        createdBy:
          type: string
          example: example@AdobeID
          description: The ID of the user that created the role.
        modifiedBy:
          type: string
          example: example@AdobeID
          description: The ID of the user that modified the role.
        modifiedAt:
          type: integer
          example: 1648153201825
          description: A timestamp to date the modification of the role.
        etag:
          type: string
          example: null
          description: A unique eTag is returned by the HTTP response.
        name:
          type: string
          example: Administrator Role
          description: The name of the role.
        description:
          type: string
          example: Role for administrator type of responsibilities and access.
          description: Additional information for the role.
        roleType:
          type: string
          example: user-defined
          description: The designated type of the role. The possible values for role type are user-defined and system-defined.
          enum:
          - user-defined
          - system-defined
        permissionSets:
          type: array
          items:
            type: string
          example:
          - view-sandboxes
          - view-schemas
          description: A group of permissions that can be applied to a role by an administrator.
        sandboxes:
          type: array
          items:
            type: string
          example:
          - prod
          description: The sandboxes within your organization that are provisioned for a particular role.
        subjectAttributes:
          type: object
          properties:
            labels:
              type: string
              example:
              - core/S1
              description: Displays the data usage labels applied to the queried role.
          description: The attributes that indicate the correlation between a subject and the Platform resources that they have access to.
    subjectsForRole:
      type: object
      properties:
        roleId:
          type: string
          description: The ID of the role.
        subjectType:
          type: string
          description: The type of queried subject.
        subjectId:
          type: string
          description: The ID that corresponds with the queried subject.
      example:
      - subjectId: 03Z07HFQCCUF3TUHAX274206@AdobeID
        subjectType: user
  parameters:
    authorization:
      name: Authorization
      in: header
      description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en). If a user token is being passed, then the user of the token must have an “org admin” role for the requested org.
      required: true
      schema:
        type: string
    content-type:
      name: Content-Type
      in: header
      description: The content type of the request body. For all requests, this value must be application/json.
      required: true
      schema:
        type: string
        enum:
        - application/json
    x-api-key:
      name: x-api-key
      in: header
      description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      in: header
      description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
x-original-swagger-version: '2.0'