First-party API boundaries¶

DotID separates browser routes, public API prefixes, and service-local controller paths. Integrations must use the public gateway contracts; service-local paths are implementation details and can change without public notice.

Browser routes¶

Browser routes load MF 2.0 applications through the account or admin gateway. The route is the console integration point, not the runtime ownership boundary: each frontend remains independently built, deployed, and released by its owning repo. DotID manages identity, launch metadata, and approved route metadata.

App	Account-console route	Admin route
StartPoint	`/startpoint/`	n/a
Account	`/account/`	n/a
Organization	`/organization/`	n/a
Identity Center	`/iam/`	n/a
QuotaCenter	`/quotacenter/`	n/a
TraceBook	`/tracebook/`	n/a
Profile	`/profile/`	`/profile/`
Notification Center	`/notifications/`	`/notifications/`

The admin console additionally hosts platform-administration apps under their own admin routes; those are not first-party integration surfaces and are not listed here.

Do not build integrations against retired aliases or rollback routes. Current gateways do not expose legacy browser aliases.

NovaBell owns the Notification Center. The DotID gateway owns /notifications/ route hosting and /novabell/notifications/... proxying; it does not own a standalone NovaBell frontend deployment.

Public API prefixes¶

Prefix	Owner	Purpose
`/accounts/v1/...`	DotID	Account discovery, sub-account creation, and account-scoped operations.
`/organizations/v1/...`	DotID	Organization discovery, OUs, and organization-scoped operations.
`/identity/v1/...`	DotID	Users, groups, service users, workload identities, and Identity Center resources.
`/audit/v1/...`	DotID Audit	Audit query and ingestion APIs.
`/quotacenter/api/...`	DotID Quota	Account quota visibility and quota request operations surfaced through QuotaCenter.
`/tracebook/api/...`	DotID Audit	Account-scoped audit event operations surfaced through TraceBook.
`/novabell/notifications/...`	NovaBell	Notification Center mailbox and stream APIs.

Service-local implementation paths are not public API contracts. They are useful in service code and tests, but clients should call the gateway capability prefixes above.

Reserved namespaces¶

/notifications/v1 is reserved and not exported for first-party Notification Center browser traffic. Browser clients call /novabell/notifications/...; the account/admin gateway forwards those requests to NovaBell’s service-local notification API.

Do not add a new public /notifications/v1 API without an ADR that defines ownership, auth headers, OpenAPI publication, and migration behavior from the current NovaBell boundary.

Required scoped headers¶

Browser calls from first-party apps are sent with the user’s bearer token and the account/session context derived by the shell.

Header	When present	Meaning
`Authorization: Bearer <token>`	Every authenticated API call	OIDC access token issued by one of DotID’s accepted realms.
`X-Account-Id`	Account-scoped calls	The active account selected in StartPoint or the shell.
`X-Session-Context-Id`	Session-aware first-party calls	Backend-issued context binding for the current shell session.

Backends must validate the token first, then derive or validate account context before making PDP decisions. Never trust a browser-supplied account ID by itself. New first-party browser clients must not depend on the retired X-Session-Identity-Scope header; use the backend-issued session context instead.

Account context from tokens¶

For flexgalaxy account-root flows, backend services should use the JWT account_id claim emitted by DotID Keycloak after normal JWT validation. The claim is a signed account UUID projection from DotID account provisioning.

Do not:

call Keycloak Admin APIs to infer account ownership;
call DotID account or authorization services on every request just to map an email address to an account;
infer account identity from preferred_username, email domain, or an acc-* realm name.

For browser console requests, continue to validate the backend-issued session context headers. The token claim identifies the root user’s owned account; it does not replace shell/session checks for active account context or account switching.

The normal first-party request path is:

Validate the bearer token and standard JWT claims.
Derive account context from the backend-issued session context or, for flexgalaxy account-root flows, the DotID-owned JWT account_id claim.
Build an AuthorizeRequest with the service action and target resource.
Call DotID PDP and enforce ALLOW or DENY.

Step 4 is required because account context is not permission. The service owns its domain resources and action names, but DotID owns the resource-based authorization model. PDP keeps managed policies, permission sets, boundaries, SCPs, delegated-admin rules, root-user behavior, and audit decision reasons consistent across all first-party services.

Platform-admin APIs use the platform/admin API boundary. They must not depend on a synthetic account-root claim or PDP root bypass.

Registering new first-party surfaces¶

New FlexGalaxy-owned services and applications register identity metadata through DotID’s Service Registration Facade. Product repos own their manifests, client registration submission, deployables, and runtime operations; DotID owns schema validation, Keycloak provisioning, IAM/action registration, audit taxonomy, and app-launch metadata.

Do not add another product’s frontend client, backend client, gateway route, or launch target directly to DotID startup code. Register the service/application from the owning repo, then let DotID reconcile the managed identity and authorization state.

Service registration is catalog-oriented. If a service later renames action strings, the owning repo must provide the old-to-new action map and DotID operators must run the internal action-rebind facility. Do not assume manifest registration rewrites installed account policy documents.