[Platform API] Authorization Design: Scope-Based Access Control for Platform API

[Thushani-Jayasekera]

Overview

This document describes the authorization model used by the Platform API. The goal is to give future developers a clear picture of how access control works end-to-end, from how scopes are defined, to how they are enforced at runtime, and how role-based tokens from external IDPs are handled.

The core design principles are:

1. OpenAPI is the source of truth. Required scopes for every endpoint are declared in openapi.yaml using the x-required-scopes extension. The enforcement middleware reads this at startup, there is no per-route permission annotation in handler code.
2. Fine-grained scopes per resource. Every resource has a discrete set of actions (create, read, update, delete, deploy, …), each represented as an individual OAuth2 scope.
3. Manage scope as a root permission. Each resource also has a :manage scope that acts as a full superset, covering read and all write operations for that resource.
4. Role → scope expansion for IDP tokens. External IDPs typically issue tokens with role names rather than fine-grained scopes. When this is the case, platform roles are mapped to their full permission set and treated as if every scope in that set were present in the token. [Not supported in first milestone]

---

Scope Reference

Endpoint Scope Reference

Required scopes per endpoint (OR-evaluated — any one scope from the list is sufficient).

Projects

Path	Required Scopes
POST /projects	api-platform:project:create, api-platform:project:manage
GET /projects	api-platform:project:read, api-platform:project:manage
GET /projects/{projectId}	api-platform:project:read, api-platform:project:manage
PUT /projects/{projectId}	api-platform:project:update, api-platform:project:manage
DELETE /projects/{projectId}	api-platform:project:delete, api-platform:project:manage

REST APIs

Path	Required Scopes
POST /rest-apis/import-openapi	api-platform:rest_api:import, api-platform:rest_api:manage
POST /rest-apis/validate-openapi	api-platform:rest_api:read, api-platform:rest_api:manage
GET /rest-apis	api-platform:rest_api:read, api-platform:rest_api:manage
POST /rest-apis	api-platform:rest_api:create, api-platform:rest_api:manage
GET /rest-apis/{apiId}	api-platform:rest_api:read, api-platform:rest_api:manage
PUT /rest-apis/{apiId}	api-platform:rest_api:update, api-platform:rest_api:manage
DELETE /rest-apis/{apiId}	api-platform:rest_api:delete, api-platform:rest_api:manage
GET /rest-apis/{apiId}/gateways	api-platform:rest_api:gateway:read, api-platform:rest_api:gateway:manage, api-platform:rest_api:manage, api-platform:gateway:read, api-platform:gateway:manage
POST /rest-apis/{apiId}/gateways	api-platform:rest_api:gateway:create, api-platform:rest_api:gateway:manage, api-platform:rest_api:manage
GET /rest-apis/{apiId}/publications	api-platform:rest_api:publication:read, api-platform:rest_api:manage
POST /rest-apis/{apiId}/publications	api-platform:rest_api:publication:create, api-platform:rest_api:manage
DELETE /rest-apis/{apiId}/publications/{devportalId}	api-platform:rest_api:publication:delete, api-platform:rest_api:manage
POST /rest-apis/{apiId}/deployments	api-platform:rest_api:deployment:create, api-platform:rest_api:deployment:manage, api-platform:rest_api:manage
GET /rest-apis/{apiId}/deployments	api-platform:rest_api:deployment:read, api-platform:rest_api:deployment:manage, api-platform:rest_api:manage
GET /rest-apis/{apiId}/deployments/{deploymentId}	api-platform:rest_api:deployment:read, api-platform:rest_api:deployment:manage, api-platform:rest_api:manage
DELETE /rest-apis/{apiId}/deployments/{deploymentId}	api-platform:rest_api:deployment:delete, api-platform:rest_api:deployment:manage, api-platform:rest_api:manage
POST /rest-apis/{apiId}/deployments/{deploymentId}/undeploy	api-platform:rest_api:deployment:undeploy, api-platform:rest_api:deployment:manage, api-platform:rest_api:manage
POST /rest-apis/{apiId}/deployments/{deploymentId}/restore	api-platform:rest_api:deployment:restore, api-platform:rest_api:deployment:manage, api-platform:rest_api:manage

REST API Keys

Path	Required Scopes
POST /rest-apis/{apiId}/api-keys	api-platform:rest_api:api_key:create, api-platform:rest_api:api_key:manage
PUT /rest-apis/{apiId}/api-keys/{keyName}	api-platform:rest_api:api_key:update, api-platform:rest_api:api_key:manage
DELETE /rest-apis/{apiId}/api-keys/{keyName}	api-platform:rest_api:api_key:delete, api-platform:rest_api:api_key:manage
GET /me/api-keys (replaced with new endpoint)	api-platform:rest_api:api_key:read, api-platform:rest_api:api_key:manage

Git

Path	Required Scopes
POST /git/repo/fetch-branches	api-platform:git:read
POST /git/repo/branch/fetch-content	api-platform:git:read

Platform Roles (Not supported in M1)

When an IDP issues role names instead of fine-grained scopes, the Platform API maps those role names to one of five built-in platform roles, each with a fixed permission set.

Platform Role	Intended persona	Permissions
admin	Platform administrator	Full access to all resources and operations, including gateway management, DevPortal administration, and subscription plan management
developer	API designer	Full API lifecycle — create, edit, deploy, publish across all resource types; cannot manage gateway infrastructure, administer DevPortals, or manage subscription plans
publisher	DevPortal manager	Read APIs across all types + publish/unpublish to DevPortals; cannot create or edit API definitions, deploy to gateways, or manage credentials
operator	CI/CD service account	Runtime lifecycle operations — gateway associations, deployments, undeploys, restores across all deployable resource types; cannot create or edit API definitions, publish, or manage credentials
viewer	Auditor / read-only consumer	Read-only access to all resources

IDP role names (e.g. PLATFORM_ADMIN, realm_developer) are mapped to platform roles via the IDP_ROLE_MAPPINGS configuration. The mapping happens during authentication so the scope enforcer always works with platform roles, not IDP-specific names.

---

Adding a New Resource

Every new resource follows the same three-step pattern.

1. Define the scopes using snake_case with colons as separators. Every resource gets a standard set:

resource:manage   — full superset, covers read and all write operations
resource:read
resource:create
resource:update
resource:delete

Add action-specific scopes alongside these where needed (resource:publish, resource:import, etc.). For sub-resources, nest the name: resource:sub_resource:action.

Please follow the rules in : #2045 (comment) (Rule 4 is not implemented in M1, kept for future reference)

2. Declare in openapi.yaml — Required scopes are declared on each operation using the standard OpenAPI security field under the OAuth2Security scheme:

---

Authorization Flow

Example — IDP_VALIDATION_MODE=scope

Config: IDP_VALIDATION_MODE=scope
Token scope claim: api-platform:rest_api:manage api-platform:project:read

Request: POST /api/v1/rest-apis
Required scopes (from OpenAPI): [api-platform:rest_api:create, api-platform:rest_api:manage]

The enforcer reads the scope claim, finds api-platform:rest_api:manage → allowed. The manage scope satisfies the create requirement because it is listed alongside rest_api:create in x-required-scopes. Roles are not looked at.

Example — IDP_VALIDATION_MODE=role (Not supported in M1)

Config: IDP_VALIDATION_MODE=role, IDP_ROLES_CLAIM_PATH=realm_access.roles, IDP_ROLE_MAPPINGS=PLATFORM_DEV=developer
Token: realm_access.roles = ["PLATFORM_DEV"]

The authentication middleware maps PLATFORM_DEV → developer and stores it as platform_roles. The scope claim is not read at all.

The scope enforcer expands the developer role to its full permission set, converts each permission to its scope string, and checks against the required scopes. Developer includes rest_api:create → allowed. The scope claim is not consulted.

---

OpenAPI as the Source of Truth

RRequired scopes are declared on each operation using the standard OpenAPI security field under the OAuth2Security scheme:

  paths:    
    /projects:
      post:
        security:
          - OAuth2Security:
              - ap:project:create
              - ap:project:manage
      get:
        security:
          - OAuth2Security:
              - ap:project:read
              - ap:project:manage

    /projects/{projectId}:
      put:
        security:
          - OAuth2Security:
              - ap:project:update
              - ap:project:manage

The list is OR-evaluated: having any one scope from the list is sufficient. Write operations always list both the specific scope and the manage scope so that both fine-grained tokens and manage-scope tokens are accepted. Scopes follow the ap:: naming convention.

At server startup, openapi.yaml is parsed, path parameters are converted from {param} to Gin's :param syntax, the server base path
(/api/v1) is prepended from the first servers[].url entry, and an in-memory lookup table is built. Handler code contains no permission
annotations. To change authorization requirements for a route, edit the security field in the OpenAPI spec only.

Operations that require no authentication declare security: [] to opt out (e.g. POST /organizations).

[renuka-fernando]

Shall we define some conventions, something like this?

Rule 1 — Lock the shape

• Format: api-platform:<resource>[:<sub-resource>]:<action>
• Colon is the only delimiter.
• snake_case for every segment, including compound names: rest_api, llm_provider, webbroker_api, api_key.
• Nest a sub-resource under its parent only when there is real ownership — the parent scopes what the child means:
  • gateway:token:create — a token belongs to a gateway
  • application:api_key:create — a key belongs to an application
  • rest_api:deployment:undeploy — a deployment belongs to a REST API

Rule 2 — CRUD verbs are a closed set

• Use exactly these for CRUD, never synonyms:

Verb	Maps to
read	GET /things and GET /things/{id}
create	POST /things
update	PUT / PATCH /things/{id}
delete	DELETE /things/{id}

• read covers both list and get-by-id.

Rule 3 — Custom verbs only for genuine non-CRUD

• Allowed for real lifecycle / bulk / sync operations: publish, unpublish, deploy, undeploy, import, export, sync, restore, …
• Naming rules:
  • snake_case
  • named after what the operation does, never after the HTTP method
  • must map to a real operation visible in the URL and/or request body — don't invent a verb to fit a scope.
• A GET with no side effects is always :read — even if the URL segment looks like a verb:

URL	Scope
GET /rest-apis/validate	rest_api:read (not :validate)
GET /…/{id}/preview	…:read (not :preview)
GET /…/{id}/diff	…:read (not :diff)

• URL casing ≠ scope casing. URLs stay kebab-case (set-default); scopes are snake_case (set_default). Don't force them to match — document the mapping in the OpenAPI extension.

Rule 4 — Wildcards: :*, own-level only

• :* covers all actions directly at that level — never descends into sub-resources, never matches a prefix (application*), never transitive.

Wildcard	Covers
api-platform:*	Every action on root-level resources (gateway:create, rest_api:read, …). Own-level like every :* — not sub-resources such as gateway:token:* or application:api_key:*.
api-platform:<resource>:*	All actions directly on the resource. Not its sub-resources.
api-platform:<resource>:<sub>:*	All actions directly on that sub-resource.

Rule 5 — URLs first, scopes follow

• Design the REST URL first; derive the scope from it. The convention constrains scope shape, not URL design.
• The scope reflects the subject being operated on, not a literal echo of the URL path:

URL	Scope	Subject
POST /rest-apis/{id}/devportals/publish	rest_api:publish	the REST API
POST /gateways/{id}/tokens	gateway:token:create	a token (owned by gateway)

[renuka-fernando]

@Thushani-Jayasekera @malinthaprasan,

I reviewed the Platform API OpenAPI specification and noticed some resource level inconsistencies. Below are my suggestions.

1. Conflicting GETs

Current	Proposed	Why
GET /rest-apis/validate (name uniqueness)	GET /rest-apis?name=&version= → empty result = available	Filter on the collection, no new path, no new scope (rest_api:read)
GET /devportals/default	Drop. Add isDefault on the devportal object; GET /devportals?default=true	Default is a property, not a resource
GET /status/gateways	Drop. Add status field on the gateway object (GET /gateways)	/gateways/status would re-create the same collision

Convention rule: never add a sibling GET literal next to GET /collection/{id}.

2. Action namespaces

Current	Proposed	Why
POST /import/openapi	POST /rest-apis/import-openapi	OpenAPI import creates a REST API, a create-variant action on /rest-apis
POST /validate/openapi	POST /rest-apis/validate-openapi	Validates a candidate OpenAPI definition for a REST API
POST /import/api-project	POST /api-projects	An API project ≠ REST API; importing it is creating it
POST /validate/api-project	POST /api-projects/validate	Validates an API-project bundle before creating it

3. Publish / unpublish → publications sub-resource

publication is already the domain's noun (the spec has GET …/publications).

Current	Proposed
POST /rest-apis/{apiId}/devportals/publish	POST /rest-apis/{apiId}/publications (body: devportalId)
POST /rest-apis/{apiId}/devportals/unpublish	DELETE /rest-apis/{apiId}/publications/{devportalId}
GET /rest-apis/{apiId}/publications	unchanged

4. Deployment actions → scope to the instance

Current	Proposed
POST /…/deployments/undeploy	POST /…/deployments/{deploymentId}/undeploy
POST /…/deployments/restore	POST /…/deployments/{deploymentId}/restore

{id}-scoped POST verbs are fine (no same-method conflict). Clarify the model: undeploy = remove from gateway, keep record; delete = remove record. (Alternative: PATCH /{id} on a status field.) Applies to all six deployment families: rest / llm-provider / llm-proxy / mcp / websub / webbroker.

5. Remove /me

Current	Proposed
GET /me/api-keys	GET /api-keys (caller's keys; owner implicit from the JWT)

6. Minor consistency

Current	Proposed	Note
…/{customPolicyUuid}/version/{version}	…/{customPolicyUuid}/versions/{version}	Plural sub-collection
GET /llm-providers/{id}/llm-proxies	GET /llm-proxies?providerId={id}	Filter over nesting (optional)
POST/GET /rest-apis/{apiId}/gateways	review vs deployments	Possible overlap — a deployment already implies a gateway

[Thushani-Jayasekera]

This is a complete summary of improvements we can do

#	Method	Deprecated Endpoint	Replacement Endpoint	Scopes
1	POST	/import/openapi	POST /rest-apis/import-openapi	ap:rest_api:import, ap:rest_api:manage
2	POST	/import/api-project	POST /api-projects/import	ap:rest_api:import, ap:rest_api:manage
3	POST	/validate/openapi	POST /rest-apis/validate-openapi	ap:rest_api:read, ap:rest_api:manage
4	POST	/validate/api-project	POST /api-projects/validate	ap:rest_api:read, ap:rest_api:manage
5	POST	/api-projects	POST /api-projects/import	ap:rest_api:import, ap:rest_api:manage
6	GET	/rest-apis/validate	GET /rest-apis?name=&version=	ap:rest_api:read, ap:rest_api:manage
7	POST	/rest-apis/{apiId}/devportals/publish	POST /rest-apis/{apiId}/publications	ap:rest_api:publication:create, ap:rest_api:manage
8	POST	/rest-apis/{apiId}/devportals/unpublish	DELETE /rest-apis/{apiId}/publications/{devportalId}	ap:rest_api:publication:delete, ap:rest_api:manage
9	POST	/rest-apis/{apiId}/deployments/undeploy	POST /rest-apis/{apiId}/deployments/{deploymentId}/undeploy	ap:rest_api:deployment:undeploy, ap:rest_api:deployment:manage, ap:rest_api:manage
10	POST	/rest-apis/{apiId}/deployments/restore	POST /rest-apis/{apiId}/deployments/{deploymentId}/restore	ap:rest_api:deployment:restore, ap:rest_api:deployment:manage, ap:rest_api:manage
11	GET	/gateway-custom-policies/{uuid}/version/{version}	GET /gateway-custom-policies/{uuid}/versions/{version}	ap:gateway_custom_policy:read, ap:gateway_custom_policy:manage
12	DELETE	/gateway-custom-policies/{uuid}/version/{version}	DELETE /gateway-custom-policies/{uuid}/versions/{version}	ap:gateway_custom_policy:delete, ap:gateway_custom_policy:manage
13	GET	/status/gateways	GET /gateways (check isActive field)	ap:gateway:read, ap:gateway:manage
14	GET	/devportals/default	GET /devportals?default=true	ap:devportal:read, ap:devportal:manage
15	POST	/llm-providers/{id}/deployments/undeploy	POST /llm-providers/{id}/deployments/{deploymentId}/undeploy	ap:llm_provider:deployment:undeploy, ap:llm_provider:deployment:manage, ap:llm_provider:manage
16	POST	/llm-providers/{id}/deployments/restore	POST /llm-providers/{id}/deployments/{deploymentId}/restore	ap:llm_provider:deployment:restore, ap:llm_provider:deployment:manage, ap:llm_provider:manage
17	POST	/llm-proxies/{id}/deployments/undeploy	POST /llm-proxies/{id}/deployments/{deploymentId}/undeploy	ap:llm_proxy:deployment:undeploy, ap:llm_proxy:deployment:manage, ap:llm_proxy:manage
18	POST	/llm-proxies/{id}/deployments/restore	POST /llm-proxies/{id}/deployments/{deploymentId}/restore	ap:llm_proxy:deployment:restore, ap:llm_proxy:deployment:manage, ap:llm_proxy:manage
19	GET	/me/api-keys	GET me/api-keys	ap:rest_api:api_key:read, ap:rest_api:api_key:manage, ap:rest_api:manage
20	POST	/mcp-proxies/{id}/deployments/undeploy	POST /mcp-proxies/{id}/deployments/{deploymentId}/undeploy	ap:mcp_proxy:deployment:undeploy, ap:mcp_proxy:deployment:manage, ap:mcp_proxy:manage
21	POST	/mcp-proxies/{id}/deployments/restore	POST /mcp-proxies/{id}/deployments/{deploymentId}/restore	ap:mcp_proxy:deployment:restore, ap:mcp_proxy:deployment:manage, ap:mcp_proxy:manage
22	POST	/websub-apis/{apiId}/devportals/publish	POST /websub-apis/{apiId}/publications	ap:websub_api:publication:create, ap:websub_api:manage
23	POST	/websub-apis/{apiId}/devportals/unpublish	DELETE /websub-apis/{apiId}/publications/{devportalId}	ap:websub_api:publication:delete, ap:websub_api:manage
24	POST	/websub-apis/{apiId}/deployments/undeploy	POST /websub-apis/{apiId}/deployments/{deploymentId}/undeploy	ap:websub_api:deployment:undeploy, ap:websub_api:deployment:manage, ap:websub_api:manage
25	POST	/websub-apis/{apiId}/deployments/restore	POST /websub-apis/{apiId}/deployments/{deploymentId}/restore	ap:websub_api:deployment:restore, ap:websub_api:deployment:manage, ap:websub_api:manage
26	POST	/webbroker-apis/{apiId}/devportals/publish	POST /webbroker-apis/{apiId}/publications	ap:webbroker_api:publication:create, ap:webbroker_api:manage
27	POST	/webbroker-apis/{apiId}/devportals/unpublish	DELETE /webbroker-apis/{apiId}/publications/{devportalId}	ap:webbroker_api:publication:delete, ap:webbroker_api:manage
28	POST	/webbroker-apis/{apiId}/deployments/undeploy	POST /webbroker-apis/{apiId}/deployments/{deploymentId}/undeploy	ap:webbroker_api:deployment:undeploy, ap:webbroker_api:deployment:manage, ap:webbroker_api:manage
29	POST	/webbroker-apis/{apiId}/deployments/restore	POST /webbroker-apis/{apiId}/deployments/{deploymentId}/restore	ap:webbroker_api:deployment:restore, ap:webbroker_api:deployment:manage, ap:webbroker_api:manage

[Thushani-Jayasekera]

Deprecated Endpoint Usage Report

Overview

This document captures the current usage of deprecated Platform API endpoints within the Management Portal codebase.

The following deprecated endpoints are currently referenced and should be migrated to their corresponding replacement endpoints.

Deprecated Endpoint References

#	Line	Method	Deprecated Endpoint	Replacement Endpoint	File
1	161	POST	/import/api-project	POST /api-projects/import	hooks/GithubAPICreation.ts
2	107	POST	/validate/api-project	POST /api-projects/validate	hooks/validation.ts
3	98	POST	/rest-apis/{apiId}/devportals/publish	POST /rest-apis/{apiId}/publications	hooks/apiPublish.ts
4	120	POST	/rest-apis/{apiId}/devportals/unpublish	DELETE /rest-apis/{apiId}/publications/{devportalId}	hooks/apiPublish.ts
5	233	GET	/status/gateways	GET /gateways (check isActive field)	hooks/gateways.ts

However, since there is no real use-case, we can remove these depreciated endpoints completely and start using new endpoints. The usages were properly updated in management portal.

These depreciated endpoints will be removed immediately as there is no usage

/import/openapi
/import/api-project
/validate/openapi
/validate/api-project
/api-projects
/rest-apis/validate
/rest-apis/{apiId}/devportals/publish
/rest-apis/{apiId}/devportals/unpublish
/status/gateways
/devportals/default
/websub-apis/{apiId}/devportals/publish
/websub-apis/{apiId}/devportals/unpublish
/webbroker-apis/{apiId}/devportals/publish
/webbroker-apis/{apiId}/devportals/unpublish

[renuka-fernando]

A few notes on the scopes in the table:

• Rows 11/12 — custom policies are org-level (no {gatewayId} parent), so ap:gateway:policy:* → ap:gateway_custom_policy:* and drop the ap:gateway:manage fallback. This applies to all five ops (collection GET/POST, /sync, both version ops), not just rows 11/12.
• Row 13 — status is a field on the gateway, not a sub-resource: ap:gateway:status:read → ap:gateway:read (keep ap:gateway:manage).

[Thushani-Jayasekera]

Platform API - Auth related configs

Mode 1: Local JWT (quickstart default)

  AUTH_JWT_ENABLED           = true
  AUTH_JWT_SECRET_KEY        = "your-secret-key-change-in-production"
  AUTH_JWT_ISSUER            = "platform-api"
  AUTH_JWT_SKIP_VALIDATION   = true   #disable in production

Mode 2: External IDP (production)

  AUTH_IDP_ENABLED           = false
  AUTH_IDP_NAME              = ""                  # e.g. "asgardeo", "keycloak" (label only)
  AUTH_IDP_JWKS_URL          = ""                  # required if ENABLED=true
  AUTH_IDP_ISSUER            = ""                  # required if ENABLED=true (comma-separated)
  AUTH_IDP_AUDIENCE          = ""                  # optional (comma-separated, supports * prefix)

Claim mappings (only needed if your IDP uses non-standard names)

  AUTH_IDP_ORGANIZATION_CLAIM_NAME   = "organization"
  AUTH_IDP_ORGANIZATIONS_CLAIM_NAME  = "organizations"
  AUTH_IDP_USER_ID_CLAIM_NAME        = "sub"
  AUTH_IDP_USERNAME_CLAIM_NAME       = "username"
  AUTH_IDP_EMAIL_CLAIM_NAME          = "email"
  AUTH_IDP_SCOPE_CLAIM_NAME          = "scope"

Validation mode: "scope" (default) or "role"

  AUTH_IDP_VALIDATION_MODE           = "scope"
  AUTH_IDP_ROLES_CLAIM_PATH          = ""          # e.g. "realm_access.roles"
  AUTH_IDP_ROLE_MAPPINGS             = ""          # e.g. "PLATFORM_ADMIN=admin,PLATFORM_DEV=developer"