Roles

Add an overview of the Admin - Roles API here. This block is preserved across regenerations.

Endpoints

GET /api/v1/permissions

List the platform RBAC permission resources catalog — what resources can be granted, which role types they apply to, and the permission levels available

get

/permissions

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Query parameters

rolestringOptional

Filter by role type (admin, customer, csr, partner) to see resources applicable to that role

Responses

200

Permission resource catalog

application/json

requestIdstringOptional

get/permissions

GET /api/v1/permissions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Permission resource catalog

{
  "data": [
    {
      "resource": "text",
      "roles": [
        "text"
      ],
      "levels": [
        "none"
      ],
      "scopes": [
        "all"
      ]
    }
  ],
  "meta": {
    "total": 1,
    "description": "text"
  },
  "requestId": "text"
}

Notes, examples, or caveats for GET /permissions go here.

GET /api/v1/roles

List all roles (profiles) for the tenant

get

/roles

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

rolestringOptional

Filter by role type (admin, customer, csr, partner)

Responses

200

Paginated list of roles

application/json

A user profile/role defining a named set of permissions

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

rolestring · enumOptionalPossible values:

isActivebooleanOptional

isSystembooleanOptional

permissionsobjectOptional

Structured permission set for this role

createdAtstring · date-timeOptional

get/roles

GET /api/v1/roles HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated list of roles

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "role": "admin",
  "isActive": true,
  "isSystem": true,
  "permissions": {},
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /roles go here.

POST /api/v1/roles

Create a new role

post

/roles

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Body

namestringRequired

rolestringRequired

descriptionstringOptional

isActivebooleanOptional

permissionsobjectOptional

Responses

201

Role created

application/json

A user profile/role defining a named set of permissions

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

rolestring · enumOptionalPossible values:

isActivebooleanOptional

isSystembooleanOptional

permissionsobjectOptional

Structured permission set for this role

createdAtstring · date-timeOptional

400

Validation error

application/json

post/roles

POST /api/v1/roles HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "name": "text",
  "role": "text",
  "description": "text",
  "isActive": true,
  "permissions": {}
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "role": "admin",
  "isActive": true,
  "isSystem": true,
  "permissions": {},
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /roles go here.

DELETE /api/v1/roles/{id}

Delete a role (system roles cannot be deleted)

delete

/roles/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Responses

204

Role deleted

No content

403

System role — cannot delete

application/json

404

Not found

application/json

delete/roles/{id}

DELETE /api/v1/roles/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /roles/{id} go here.

GET /api/v1/roles/{id}

Get role details

get

/roles/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Responses

200

Role details

application/json

A user profile/role defining a named set of permissions

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

rolestring · enumOptionalPossible values:

isActivebooleanOptional

isSystembooleanOptional

permissionsobjectOptional

Structured permission set for this role

createdAtstring · date-timeOptional

404

Not found

application/json

get/roles/{id}

GET /api/v1/roles/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "role": "admin",
  "isActive": true,
  "isSystem": true,
  "permissions": {},
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /roles/{id} go here.

PATCH /api/v1/roles/{id}

Update a role

patch

/roles/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Body

namestringOptional

descriptionstringOptional

isActivebooleanOptional

permissionsobjectOptional

Responses

200

Role updated

application/json

A user profile/role defining a named set of permissions

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

rolestring · enumOptionalPossible values:

isActivebooleanOptional

isSystembooleanOptional

permissionsobjectOptional

Structured permission set for this role

createdAtstring · date-timeOptional

404

Not found

application/json

patch/roles/{id}

PATCH /api/v1/roles/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "name": "text",
  "description": "text",
  "isActive": true,
  "permissions": {}
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "role": "admin",
  "isActive": true,
  "isSystem": true,
  "permissions": {},
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for PATCH /roles/{id} go here.

GET /api/v1/roles/{id}/permissions

Get the permission set for a role

get

/roles/{id}/permissions

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Responses

200

Permission object for this role

No content

404

Role not found

application/json

get/roles/{id}/permissions

GET /api/v1/roles/{id}/permissions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /roles/{id}/permissions go here.

PATCH /api/v1/roles/{id}/permissions

Update the permission set for a role

patch

/roles/{id}/permissions

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Body

resourcesobjectOptional

navigationGroupsobjectOptional

catalogGrantsobjectOptional

Responses

200

Permissions updated

No content

403

Forbidden (system Administrator role)

application/json

404

Role not found

application/json

patch/roles/{id}/permissions

PATCH /api/v1/roles/{id}/permissions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 57

{
  "resources": {},
  "navigationGroups": {},
  "catalogGrants": {}
}

No content

Notes, examples, or caveats for PATCH /roles/{id}/permissions go here.