openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses Custom API Role Policies API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
contact:
name: Elastic Path
url: https://www.elasticpath.com
email: support@elasticpath.com
license:
url: https://elasticpath.dev
name: MIT
servers:
- url: https://useast.api.elasticpath.com
description: US East
- url: https://euwest.api.elasticpath.com
description: EU West
security:
- BearerToken: []
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:
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
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
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
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
responses:
CustomAPIRolePolicy:
description: A Custom API Role Policy
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomAPIRolePolicy'
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"
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"
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"
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"
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"
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'
requestBodies:
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
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
schemas:
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 Role.
example: it-developer
type:
type: string
description: Specifies the type of the resource object.
enum:
- standard_user_role
- standard_shopper_role
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
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'
LinkURI:
type:
- string
- 'null'
format: uri
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
securitySchemes:
BearerToken:
type: http
scheme: bearer