Roles and Privileges
Enforcement model
Authorization is enforced per route against a required privilege, with an optional admin check:
- If
AUTH_ENABLED=false→ bypass (local dev only). - Otherwise the request’s JWT is validated for the required privilege. A missing/invalid token →
AUTHENTICATION_REQUIRED(401). - If the token lacks the privilege, or the route requires admin and the user is not an admin →
UNAUTHORIZED_APP_ACCESS(403).
JWT claims are configurable: roles from JWT_ROLES_CLAIM (default cognito:groups), privileges from JWT_PRIVILEGES_CLAIM (default custom:privileges), username from JWT_USERNAME_CLAIM (default cognito:username).
Self‑registration uses a separate machine‑to‑machine mechanism: it validates the hashed X-App-Api-Key, checks expiry, and blocks keys whose owning app is deprecated/archived/rejected/deleted (APP_NOT_ACTIVE). Max 5 active keys per app.
Full privilege list (as used in routes)
| Privilege | Used by |
|---|---|
marketplace:createApp |
Create + quick‑create apps |
marketplace:readApp |
List/read apps, versions, connector metadata, merchant stores, interfaces (read), enabled apps, canary status, per‑app history |
marketplace:updateApp |
Update app, status transition, publish/deprecate version |
marketplace:deleteApp (admin) |
Delete app |
marketplace:manageApp |
API‑key create/revoke (registry) |
marketplace:manageApps (mostly admin) |
Store & business enablement, drain, rollback, set‑default, routing, hooks, canary promote/rollback |
marketplace:manageInterfaces (admin) |
Create/update/delete interface definitions |
marketplace:readAppConfig |
Read config overrides, effective config, list/test mocks |
marketplace:manageAppConfig |
Set/patch/delete config overrides, manage mocks, payment config (set/delete), provider routing |
marketplace:viewAppConfig |
Read payment config |
marketplace:manageWebhooks |
Create/update/delete/deliver webhooks (delete = admin) |
marketplace:readWebhooks |
List webhooks, view deliveries |
marketplace:auditor |
App/enablement/webhook audit logs, history compare, snapshot |
marketplace:notification:event:create / :view / :update / :delete |
Notification events + restricted events + readiness |
marketplace:notification:action:create / :view / :update / :delete |
Notification actions |
No static “roles” table is defined; roles come from the JWT (
JWT_ROLES_CLAIM) and authorization is privilege‑based. Routes marked (admin) add an admin check on top of the privilege.
Revision History
2026-08-05 | JP – Created the page and added the content.