Elastic Path Custom API Role Policies API

openapi: 3.2.0
info:
  title: Permissions Introduction Custom API Role Policies API
  description: 'A user''s permissions are determined by their assigned role, which defines their level of access to APIs and Commerce Manager. These permissions ensure that users can only perform actions and access data relevant to their responsibilities.


    With [Commerce Extensions](/docs/api/commerce-extensions/commerce-extensions-introduction), you can create Custom APIs to extend the functionality of Commerce. Using Custom API Role Policies, you can specify the permissions for each role, ensuring fine-grained control over who can interact with these Custom APIs.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  version: 26.0610.7728570
  x-version-timestamp: 2026-06-10 00:02:14+00:00
  license:
    name: MIT
    url: assets/LICENSE
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- bearerAuth: []
tags:
- name: Custom API Role Policies
  description: 'A Custom API Role Policy defines the level of access a role has to a Custom API. By default, administrative roles like **Store Admin** or **Org Admin** have full access to all Custom APIs. To grant access to other roles, a policy must be created for that specific role and Custom API.


    Below are the permissions that can be assigned to a role:


    | Permission | Description                              |

    |------------|------------------------------------------|

    | **Create** | Create a Custom API Entry.               |

    | **List**   | Retrieve a list of Custom API Entries.   |

    | **Read**   | Get a Custom API Entry.                  |

    | **Update** | Update a Custom API Entry.               |

    | **Delete** | Delete a Custom API Entry.               |

    '
paths:
  /v2/permissions/custom-api-role-policies:
    post:
      tags:
      - Custom API Role Policies
      summary: Create A Custom API Role Policy
      operationId: CreateACustomAPIRolePolicy
      description: Create A Custom API Role Policy
      requestBody:
        $ref: '#/components/requestBodies/CreateCustomAPIRolePolicy'
      responses:
        '201':
          $ref: '#/components/responses/CustomAPIRolePolicy'
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Custom API Role Policies
      summary: List Custom API Role Policies
      operationId: ListCustomAPIRolePolicies
      description: 'Retrieves a list of Custom API Role Policies


        ## Filtering

        The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) Custom API Role Policies:


        | Attribute        | Operators                     | Example                                                  |

        |------------------|-------------------------------|----------------------------------------------------------|

        | `id`             | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,3fa85f64-5717-4562-b3fc-2c963f66afa6)`            |

        | `created_at`     | `lt`,`le`,`eq`,`gt`,`ge`      | `ge(created_at,2024-04-29T00:00:00.000Z)`                |

        | `updated_at`     | `lt`,`le`,`eq`,`gt`,`ge`      | `le(updated_at,2024-04-29T00:00:00.000Z)`                |

        | `custom_api_id`  | `eq`                          | `eq(custom_api_id,fded1d2a-8bb8-48b6-86a5-9eb05cc8626a)` |

        | `role_id`        | `eq`                          | `eq(role_id,it-developer)`                               |


        ## Sorting

        The following attributes are available for sorting. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default sort order is `created_at` in descending order.

        - `id`

        - `created_at`

        - `updated_at`

        '
      parameters:
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/CustomAPIRolePolicySort'
      responses:
        '200':
          $ref: '#/components/responses/ListOfCustomAPIRolePolicies'
        '400':
          $ref: '#/components/responses/BadFilterError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/permissions/custom-api-role-policies/{custom-api-role-policy-id}:
    parameters:
    - $ref: '#/components/parameters/CustomAPIRolePolicyId'
    get:
      tags:
      - Custom API Role Policies
      summary: Get a Custom API Role Policy
      operationId: GetACustomAPIRolePolicy
      description: Get A Custom API Role Policy
      responses:
        '200':
          $ref: '#/components/responses/CustomAPIRolePolicy'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Custom API Role Policies
      summary: Update a Custom API Role Policy
      operationId: UpdateACustomAPIRolePolicy
      description: Update A Custom API Role Policy
      requestBody:
        $ref: '#/components/requestBodies/UpdateCustomAPIRolePolicy'
      responses:
        '200':
          $ref: '#/components/responses/CustomAPIRolePolicy'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Custom API Role Policies
      summary: Delete a Custom API Role Policy
      operationId: DeleteACustomAPIRolePolicy
      description: Delete A Custom API Role Policy
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    Filter:
      name: filter
      description: Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.
      in: query
      required: false
      schema:
        type: string
        format: string
    CustomAPIRolePolicySort:
      name: sort
      description: Specifies the order in which Custom API Role Policies will be returned.
      in: query
      required: false
      schema:
        type: string
        enum:
        - id
        - -id
        - created_at
        - -created_at
        - updated_at
        - -updated_at
        example: id
        x-enumDescriptions:
          id: Sort in increasing order of ID
          -id: Sort in decreasing order of ID
          created_at: Sort in increasing order of creation
          -created_at: Sort in decreasing order of creation
          updated_at: Sort in increasing order of last update
          -updated_at: Sort in decreasing order of last update
    PageOffset:
      name: page[offset]
      description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.
      in: query
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        maximum: 10000
    CustomAPIRolePolicyId:
      name: custom-api-role-policy-id
      description: The ID of the Custom API Role Policy.
      in: path
      required: true
      schema:
        type: string
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    PageLimit:
      name: page[limit]
      description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.
      in: query
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
  schemas:
    LinkURI:
      type:
      - string
      - 'null'
      format: uri
    PaginationLinks:
      type: object
      properties:
        current:
          $ref: '#/components/schemas/LinkURI'
          description: Always the current page.
          example: /v2/settings/custom-apis?page[offset]=0&page[limit]=100
        first:
          $ref: '#/components/schemas/LinkURI'
          description: Always the first page.
          example: /v2/settings/custom-apis?page[offset]=0&page[limit]=100
        last:
          $ref: '#/components/schemas/LinkURI'
          description: Always `null` if there is only one page.
          example: /v2/settings/custom-apis?page[offset]=0&page[limit]=100
        next:
          $ref: '#/components/schemas/LinkURI'
          description: Always `null` if there is only one page.
          example: null
        prev:
          $ref: '#/components/schemas/LinkURI'
          description: Always `null` if on the first page.
          example: null
    PaginationMeta:
      type: object
      properties:
        results:
          type: object
          properties:
            total:
              type: integer
              description: Total number of results for the entire collection.
        page:
          type: object
          properties:
            limit:
              type: integer
              description: The maximum number of records for all pages.
              example: 100
            offset:
              type: integer
              description: The current offset by number of pages.
              example: 0
            current:
              type: integer
              description: The current number of pages.
              example: 1
            total:
              type: integer
              description: The total number of pages.
              example: 1
    Errors:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
            - status
            - title
            properties:
              status:
                type: string
                description: The HTTP response code of the error.
                format: string
                examples:
                - '400'
              title:
                type: string
                description: A brief summary of the error.
                examples:
                - Bad Request
              detail:
                type: string
                description: Optional additional detail about the error.
                examples:
                - The field 'name' is required
    CustomAPIRolePolicyRelationships:
      type: object
      properties:
        custom_api:
          type: object
          properties:
            data:
              type: object
              properties:
                id:
                  type: string
                  description: The unique identifier for the related Custom API.
                  example: 652e39d8-d613-493e-8c20-fef99ad6327a
                type:
                  type: string
                  description: Specifies the type of the resource object.
                  const: custom_api
        role:
          type: object
          properties:
            data:
              type: object
              properties:
                id:
                  type: string
                  description: The unique identifier for the related Role.
                  example: it-developer
                type:
                  type: string
                  description: Specifies the type of the resource object.
                  enum:
                  - standard_user_role
                  - standard_shopper_role
    Meta:
      type: object
      properties:
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    Timestamps:
      type: object
      properties:
        created_at:
          type: string
          description: Specifies the date the entity is created.
          example: '2017-01-10T11:41:19.244Z'
        updated_at:
          type: string
          description: Specifies the date the entity is last updated.
          example: '2017-01-10T11:41:19.244Z'
    CustomAPIRolePolicy:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the Custom API Role Policy.
          format: uuid
        type:
          type: string
          description: Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.
          const: custom_api_role_policy
        create:
          type: boolean
          description: Specifies if the Role can create a Custom API Entry.
        list:
          type: boolean
          description: Specifies if the Role can retrieve a list of Custom API Entries.
        read:
          type: boolean
          description: Specifies if the Role can get a Custom API Entry.
        update:
          type: boolean
          description: Specifies if the Role can update a Custom API Entry.
        delete:
          type: boolean
          description: Specifies if the Role can delete a Custom API Entry.
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/LinkURI'
              description: Specifies the URI of the Custom API Role Policy.
              example: /v2/permissions/custom-api-role-policies/3fa85f64-5717-4562-b3fc-2c963f66afa6
        meta:
          $ref: '#/components/schemas/Meta'
        relationships:
          $ref: '#/components/schemas/CustomAPIRolePolicyRelationships'
  requestBodies:
    CreateCustomAPIRolePolicy:
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                type: object
                required:
                - type
                - create
                - list
                - read
                - update
                - delete
                - relationships
                properties:
                  type:
                    type: string
                    description: Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.
                    const: custom_api_role_policy
                  create:
                    type: boolean
                    description: Specifies if the Role can create a Custom API Entry.
                  list:
                    type: boolean
                    description: Specifies if the Role can retrieve a list of Custom API Entries.
                  read:
                    type: boolean
                    description: Specifies if the Role can get a Custom API Entry.
                  update:
                    type: boolean
                    description: Specifies if the Role can update a Custom API Entry.
                  delete:
                    type: boolean
                    description: Specifies if the Role can delete a Custom API Entry.
                  relationships:
                    $ref: '#/components/schemas/CustomAPIRolePolicyRelationships'
          examples:
            Create Example:
              summary: Create a Custom API Role Policy
              value:
                data:
                  type: custom_api_role_policy
                  create: true
                  list: false
                  read: true
                  update: false
                  delete: true
                  relationships:
                    custom_api:
                      data:
                        id: fded1d2a-8bb8-48b6-86a5-9eb05cc8626a
                        type: custom_api
                    role:
                      data:
                        id: it-developer
                        type: standard_user_role
    UpdateCustomAPIRolePolicy:
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                type: object
                required:
                - type
                properties:
                  type:
                    type: string
                    description: Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.
                    const: custom_api_role_policy
                  create:
                    type: boolean
                    description: Specifies if the Role can create a Custom API Entry.
                  list:
                    type: boolean
                    description: Specifies if the Role can retrieve a list of Custom API Entries.
                  read:
                    type: boolean
                    description: Specifies if the Role can get a Custom API Entry.
                  update:
                    type: boolean
                    description: Specifies if the Role can update a Custom API Entry.
                  delete:
                    type: boolean
                    description: Specifies if the Role can delete a Custom API Entry.
          examples:
            Update Example:
              summary: Update a Custom API Role Policy
              value:
                data:
                  type: custom_api_role_policy
                  create: false
                  list: false
                  read: false
                  update: false
                  delete: false
  responses:
    ConflictError:
      description: Unable to perform the operation at this time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          examples:
            duplicate-custom-api:
              summary: Duplicate Custom API
              value: "{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"
            duplicate-custom-field:
              summary: Duplicate Custom Field
              value: "{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"
    NotFoundError:
      description: Not found. The requested entity does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          examples:
            not-found:
              summary: Requested entity not found
              value: "{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"
    CustomAPIRolePolicy:
      description: A Custom API Role Policy
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/CustomAPIRolePolicy'
    BadFilterError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          examples:
            missing-name:
              summary: Required field missing
              value: "{\n  \"errors\": [\n    {\n      \"detail\": \"Invalid filter: unknown field [version] specified in search filter, allowed fields are [api_type created_at description id name slug updated_at]\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"
    ValidationError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          examples:
            missing-name:
              summary: Required field missing
              value: "{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"
    ListOfCustomAPIRolePolicies:
      description: List of Custom API Role Policies
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/CustomAPIRolePolicy'
              meta:
                $ref: '#/components/schemas/PaginationMeta'
              links:
                $ref: '#/components/schemas/PaginationLinks'
    InternalServerError:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          examples:
            internal-server-error:
              summary: Internal server error
              value: "{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer