openapi: 3.1.0
info:
  title: Permissions Introduction
  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.0224.7243234
  x-version-timestamp: 2026-02-24T22:30:07Z
  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: Built-in Roles
    description: |
      Built-in Roles represent the various personas supported in Commerce. Some Roles pertain to store management and can be assigned to users through Commerce Manager, while others represent customers who shop at the store.
  - 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/built-in-roles:
    get:
      tags:
        - Built-in Roles
      summary: List Built-in Roles
      operationId: ListBuiltInRoles
      description: |
        Retrieves a list of Built-in Roles
      responses:
        '200':
          $ref: '#/components/responses/ListOfBuiltInRoles'
        '400':
          $ref: '#/components/responses/BadFilterError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/permissions/built-in-roles/{built-in-role-id}:
    parameters:
      - $ref: '#/components/parameters/BuiltInRoleId'
    get:
      tags:
        - Built-in Roles
      summary: Get a Built-in Role
      operationId: GetABuiltInRole
      description: Get a Built-in Role
      responses:
        '200':
          $ref: '#/components/responses/BuiltInRole'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    LinkURI:
      type:
        - string
        - 'null'
      format: uri
    BuiltInRole:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the Built-in Role.
        type:
          type: string
          description: Specifies the type of the resource object, use `built_in_role` for Built-in Roles.
          const: built_in_role
        name:
          type: string
          description: Specifies the name of the Built-in Role.
        cm_user_assignable:
          type: boolean
          description: Specifies if the Built-in Role can be assigned to a user in Commerce Manager.
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/LinkURI'
              description: Specifies the URI of the Built-In Role.
              example: /v2/permissions/built-in-roles/it-developer
    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
    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'
    Meta:
      type: object
      properties:
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    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 Built-In Role.
                  example: it-developer
                type:
                  type: string
                  description: Specifies the type of the resource object.
                  const: built_in_role
    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 Built-in Role can create a Custom API Entry.
        list:
          type: boolean
          description: Specifies if the Built-in Role can retrieve a list of Custom API Entries.
        read:
          type: boolean
          description: Specifies if the Built-in Role can get a Custom API Entry.
        update:
          type: boolean
          description: Specifies if the Built-in Role can update a Custom API Entry.
        delete:
          type: boolean
          description: Specifies if the Built-in 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'
    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
    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
  responses:
    ListOfBuiltInRoles:
      description: List of Built-in Roles
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/BuiltInRole'
    BadFilterError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          examples:
            missing-name:
              summary: Required field missing
              value: |
                {
                  "errors": [
                    {
                      "detail": "Invalid filter: unknown field [version] specified in search filter, allowed fields are [api_type created_at description id name slug updated_at]",
                      "status": "400",
                      "title": "Bad Request"
                    }
                  ]
                }
    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: |
                {
                  "errors": [
                    {
                      "title": "Internal Server Error",
                      "status": "500",
                      "detail": "there was a problem processing your request"
                    }
                  ]
                }
    BuiltInRole:
      description: A Built-in Role
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/BuiltInRole'
    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: |
                {
                  "errors": [
                    {
                      "title": "Not Found",
                      "status": "404",
                      "detail": "Not found"
                    }
                  ]
                }
    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'
    CustomAPIRolePolicy:
      description: A Custom API Role Policy
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/CustomAPIRolePolicy'
    ValidationError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          examples:
            missing-name:
              summary: Required field missing
              value: |
                {
                  "errors": [
                    {
                      "title": "Bad Request",
                      "status": "400",
                      "detail": "The field 'name' is required."
                    }
                  ]
                }
    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: |
                {
                  "errors": [
                    {
                      "title": "Conflict",
                      "status": "409",
                      "detail": "custom_api with the given api_type already exists"
                    }
                  ]
                }
            duplicate-custom-field:
              summary: Duplicate Custom Field
              value: |
                {
                  "errors": [
                    {
                      "title": "Conflict",
                      "status": "409",
                      "detail": "custom_field with the given slug already exists"
                    }
                  ]
                }
  parameters:
    BuiltInRoleId:
      name: built-in-role-id
      description: The ID of the Built-In Role.
      in: path
      required: true
      schema:
        type: string
      example: it-developer
    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
    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
    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
    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
  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 Built-in Role can create a Custom API Entry.
                  list:
                    type: boolean
                    description: Specifies if the Built-in Role can retrieve a list of Custom API Entries.
                  read:
                    type: boolean
                    description: Specifies if the Built-in Role can get a Custom API Entry.
                  update:
                    type: boolean
                    description: Specifies if the Built-in Role can update a Custom API Entry.
                  delete:
                    type: boolean
                    description: Specifies if the Built-in 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: built_in_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 Built-in Role can create a Custom API Entry.
                  list:
                    type: boolean
                    description: Specifies if the Built-in Role can retrieve a list of Custom API Entries.
                  read:
                    type: boolean
                    description: Specifies if the Built-in Role can get a Custom API Entry.
                  update:
                    type: boolean
                    description: Specifies if the Built-in Role can update a Custom API Entry.
                  delete:
                    type: boolean
                    description: Specifies if the Built-in 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