Install the Company Roles Backend API

This document describes how to install the Company Roles Backend API, which exposes company role data at /company-roles and the permissions a role can hold at /company-role-permissions through the Glue Backend application. Both resources ship together and are installed by this guide. For the endpoint reference, see Backend API: Manage company roles and Backend API: Manage company role permissions.

Prerequisites

Install the required features:

Step 1 installs the remaining modules the API depends on, so you do not have to install them beforehand.

Install feature core

1) Install the required modules

Install the feature using Composer:

composer require spryker-feature/customer-experience-management --update-with-dependencies

2) Check the API Platform configuration

The resource schemas ship inside the installed package, at vendor/spryker-feature/customer-experience-management/resources/api/backend/company-roles.resource.yml and company-role-permissions.resource.yml. The generator finds them as long as the Glue Backend application serves the backend API type and scans the directory the feature is installed into.

In config/GlueBackend/packages/spryker_api_platform.php, confirm that apiTypes() includes backend. Leave sourceDirectories() alone unless your project overrides it—the default already covers installed packages. For what both settings do, see Configuration.

Also confirm that config/GlueBackend/bundles.php registers SprykerApiPlatformBundle and ApiPlatformBundle. If it does not, your project has not enabled API Platform for the Glue Backend yet—see Enable API Platform.

3) Set up the database schema and transfer objects

Apply the database schema changes and generate the transfer objects:

docker/sdk console transfer:generate
docker/sdk console propel:install

4) Back-fill the company role UUIDs

The UUID behavior fills uuid when a company role is saved, so roles that existed before the column was added have an empty uuid and cannot be addressed by the API. Generate the missing values:

docker/sdk console uuid:generate CompanyRole spy_company_role

select count(*) from spy_company_role where uuid is NULL;

5) Synchronize the permissions

/company-role-permissions lists the permission plugins registered in your project, joined with the spy_permission rows that store them. A permission plugin that has never been synchronized is missing from that table and cannot be assigned to a role.

Permissions are written to spy_permission by the installer plugins that projects wire into InstallerDependencyProvider::getInstallerPlugins()—for example SharedCartPermissionInstallerPlugin and ShoppingListPermissionsInstallerPlugin. Run the installer:

docker/sdk console setup:init-db

select count(*) from spy_permission;

6) Generate the API resources

Generate the API resources, then clear the Glue Backend kernel cache:

docker/sdk cli "GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue api:generate"
rm -rf data/cache/GlueBackend/*

Verification

Request a Back Office access token as described in Authenticate as a Back Office user, then retrieve a company role collection.

Retrieve a company role collection

curl "https://glue-backend.mysprykershop.com/company-roles?page[limit]=1" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/vnd.api+json"

The integration is successful when the request returns 200 with a data array and a meta.pagination object.

Retrieve the available permissions

curl "https://glue-backend.mysprykershop.com/company-role-permissions?page[limit]=5" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/vnd.api+json"

The request returns 200 with one entry per permission, each carrying a key and its localizedNames. An empty collection means step 5 has not run.

Create a company role to confirm the write path:

curl -X POST "https://glue-backend.mysprykershop.com/company-roles" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"company-roles","attributes":{"name":"Approver","companyUuid":"{company_uuid}","permissionKeys":["ApproveQuotePermissionPlugin"]}}}'

The request returns 201 Created with the created company role.

Troubleshooting