Architecture and request flows

Trust boundaries

The browser talks only to the Music API for account-scoped Ngamia requests. The Music API owns OAuth code exchange and session cookies. The Ngamia API remains authoritative for models, user profile, library, billing, activity, generation, and payments. Camel Accounts authenticates the user’s identity; the Music API exchanges its access token for a Ngamia account token pair.

The callback component is responsible for validating the returned OAuth state before submitting the code. The backend validates that code is a non-empty string and that code_verifier is at least 43 characters; provider-side PKCE validation remains part of the token exchange.

Access token refresh during an authenticated request

Refresh is transparent within authenticatedNgamiaFetch: it retries only after a 401 when a refresh cookie exists. It does not retry other statuses. If refresh itself throws, the original response is returned; if it returns no valid token pair, cookies are cleared.

Track generation activity

Generation can take up to 280 seconds for the upstream fetch. The NestJS service does not declare a route-level platform duration, so the host’s request timeout must be configured above the expected generation time. A timeout returns a 502 advising the client to check activity before retrying because an upstream generation may have completed despite the timeout.

Public playback activity

Only GET /v1/music/public/:id and GET /v1/music/public/:id/content take the unauthenticated proxy branch. The current middleware’s regular expression includes the query string, so these public paths must be requested without query parameters to take that branch. The Ngamia API still decides whether a creation is public. Other proxy requests use the account session.

Main web-app call sequence

After GET /api/auth/session returns a profile, the studio loads models, billing balance, music creations, recent activity, and a monthly summary. Generate action then refreshes creations, balance, and activity. Library visibility changes use PATCH /api/ngamia/v1/music/creations/:id; content playback uses its /content route. The workflow guides document the relevant request shapes.