Roles

Roles define what a team member can access within a project. There are two built-in roles (Owner and Developer) and you can create custom roles with specific permissions.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/store/roles	Admin	List all roles
POST	/v1/store/roles	Admin + roles	Create a custom role
PATCH	/v1/store/roles/{slug}	Admin + roles	Update a custom role

---

Built-in roles

These roles are always available and cannot be modified or archived.

Role	Slug	Permissions
Owner	owner	All permissions
Developer	developer	All except billing

Permission sections

Permissions are granted at the section level. Each section covers a group of related features.

Key	Label	Covers
catalog	Catalog	Products, collections, images, tags
orders	Orders	Orders, fulfillment
customers	Customers	Customers, addresses
promotions	Promotions	Promotions
inventory	Inventory	Inventory adjustments
shipping	Shipping	Shipping zones and rates
settings	Settings	General and commerce settings
billing	Billing	Plan, payment, invoices
developer	Developer	API keys, webhooks, redirects
team	Team	Invite, change roles, remove members
roles	Roles	Create, edit, archive roles

---

List roles

GET /v1/store/roles

Returns all role definitions for the project, including built-in roles and custom roles.

Request

curl https://api.hydrajs.dev/v1/store/roles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
	"data": [
		{
			"key": "owner",
			"slug": "owner",
			"label": "Owner",
			"permissions": [
				"catalog",
				"orders",
				"customers",
				"promotions",
				"inventory",
				"shipping",
				"settings",
				"billing",
				"developer",
				"team",
				"roles"
			],
			"is_built_in": true,
			"archived": false
		},
		{
			"key": "developer",
			"slug": "developer",
			"label": "Developer",
			"permissions": [
				"catalog",
				"orders",
				"customers",
				"promotions",
				"inventory",
				"shipping",
				"settings",
				"developer",
				"team",
				"roles"
			],
			"is_built_in": true,
			"archived": false
		},
		{
			"key": "role_1",
			"slug": "content-editor",
			"label": "Content Editor",
			"permissions": ["catalog"],
			"is_built_in": false,
			"archived": false,
			"created_at": "2026-06-15T10:00:00.000Z"
		}
	]
}

---

Create a custom role

POST /v1/store/roles

Creates a new custom role. The slug is auto-generated from the label if not provided. Requires the roles permission.

Request body

Field	Type	Required	Description
label	string	Yes	Display name for the role
slug	string	No	URL-friendly identifier (auto-generated from label if omitted)
permissions	string[]	Yes	Array of permission section keys

Request

curl -X POST https://api.hydrajs.dev/v1/store/roles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Content Editor",
    "permissions": ["catalog"]
  }'

Response 201

{
	"data": {
		"key": "role_1",
		"slug": "content-editor",
		"label": "Content Editor",
		"permissions": ["catalog"],
		"is_built_in": false,
		"archived": false,
		"created_at": "2026-08-20T10:00:00.000Z"
	}
}

---

Update a custom role

PATCH /v1/store/roles/{slug}

Updates a custom role’s label, slug, permissions, or archived status. Built-in roles cannot be modified. Requires the roles permission.

Request body

All fields are optional. Only provided fields are updated.

Field	Type	Description
label	string	New display name
slug	string	New slug (must be unique, not reserved)
permissions	string[]	New permission set
archived	boolean	Set to true to archive the role

Request — update permissions

curl -X PATCH https://api.hydrajs.dev/v1/store/roles/content-editor \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissions": ["catalog", "orders"]}'

Response 200

{
	"data": {
		"key": "role_1",
		"slug": "content-editor",
		"label": "Content Editor",
		"permissions": ["catalog", "orders"],
		"is_built_in": false,
		"archived": false,
		"created_at": "2026-06-15T10:00:00.000Z"
	}
}

Request — archive a role

curl -X PATCH https://api.hydrajs.dev/v1/store/roles/content-editor \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}'

---

The role object

Field	Type	Description
key	string	Internal key (owner, developer, or role_1, role_2, etc.)
slug	string	URL-friendly identifier used in API calls
label	string	Human-readable display name
permissions	string[]	Array of permission section keys
is_built_in	boolean	true for Owner and Developer
archived	boolean	Whether the role is archived
created_at	string	ISO 8601 timestamp (custom roles only)