Projects, environments and releases
This internal API prepares deployable applications without altering the DSL catalogue or publishing infrastructure. Its operational routes require a platform user session and a live OWNER/ADMIN membership in the active company. Direct promotion requires Nimo's confidential OAuth principal and the nimo:application-projects:promote scope; a USER JWT receives 403. The SPA promotes through the cookie-only BFF. The assignment remains shareable=false and publicSafe=false; it is not exposed to API keys, app clients, the public SDK, external MCP or the embeddable chat.
| Method | Route | Input | Result |
|---|---|---|---|
| GET | /app-projects?page=1&limit=20 | page ≥ 1; limit 1–100 (default 20) | 200: { data, total, page, limit }, the active company's projects |
| POST | /app-projects | { name, sourceType: "dsl", applicationRef } or { name, sourceType: "git-static" } | 201: project; creates preview and production with configuration revision 1 and different namespaces |
| POST | /app-projects/:id/releases | DSL: { sourceVersion: 1 }; Git: { commitSha: "<full 40/64 hex SHA>" } | 201: release with snapshot, hash and format version |
| POST | /app-projects/:projectId/releases/:releaseId/artifact | No body | Compiles an immutable DSL bundle; requires a live OWNER/ADMIN. sourceHash stays separate from artifactHash |
| GET | /app-projects/:projectId/releases/:releaseId/artifact | Project and release UUIDs | Manifest and artifact URL; requires a live OWNER/ADMIN |
| GET | /app-projects/:id/environments | Project UUID | 200: environments with configRevision, releaseGeneration, dataNamespace, currentRelease |
| GET | /app-projects/:projectId/environments/:environmentId/connections | Project and environment UUIDs | Four policies and a diagnostic; never returns credentials |
| PUT | /app-projects/:projectId/environments/:environmentId/connections | expectedRevision and the policy for payment/email/push/webhook | New revision with references to active tenant providers. Preview rejects productive connections; sandbox without an adapter and push/webhook fail 422 without writing; stale revision: 409 |
| GET | /app-projects/:projectId/environments/:environmentId/runtime-origins | Project and environment UUIDs | List of exact active and retired origins |
| POST | /app-projects/:projectId/environments/:environmentId/runtime-origins | { origin } | Registers an exact HTTPS origin (localhost/loopback HTTP only in development); no wildcard, credentials, path, query or fragment |
| DELETE | /app-projects/:projectId/environments/:environmentId/runtime-origins/:originId | Project, environment and origin UUIDs | Retires the origin and immediately denies bound sessions |
| POST | /app-projects/:projectId/environments/:environmentId/runtime-sessions | { originId, expiresInSeconds?: 60..3600 } | Issues a single-use opaque nrs_… credential with 15 min by default, bound to user/app/company/project/environment/release/origin |
| DELETE | /app-projects/runtime-sessions/:id | UUID of the current user's session | Immediate revocation; the next request returns 401 |
| POST | /app-operations | Idempotency-Key + { projectId, environmentId, releaseId, operationType: deployment|hosting-migration|hosting-rollback, expectedGeneration } | 201: operationId persisted before dispatch; migration/rollback only on the current release; a repeated key with the same input returns the operation, different input: 409 |
| POST | /app-environments/:id/promotions | Internal Nimo OAuth with the nimo:application-projects:promote scope; promotion payload | 201: activates the release tested in Preview; a normal USER JWT: 403; stale revision or active operation: 409 |
| GET | /app-operations/:id | Operation UUID | 200: state and sanitized evidence for the active company; another company or nonexistent: 404 |
| POST | /app-operations/:id/cancel | Operation UUID | 200: cancelled; finished operation: 409 |
The operations require a platform user with a live OWNER/ADMIN membership and are not exposed to the public SDK, external MCP or the embeddable chat. The durable table keeps the operation if the process restarts; an idempotency key cannot be reused with a different input. Migration and rollback store a snapshot of release, route, configuration revision and data namespace. If any of them changes before the cut, the operation fails without changing the active route. WfP never executes customer code, and temporary asset JWTs are not stored on the operation.
Cookie-only BFF for Nimo promotion
These routes are part of neither OpenAPI nor the public SDKs. They require the exact Origin from NIMO_INTERNAL_BFF_ORIGIN and the host-only __Secure-nimo_bff_session cookie with Secure, HttpOnly, SameSite=Lax, Path=/ai/internal/bff and a 15-minute TTL. Login validates the password and an active OWNER/ADMIN membership. It issues no JWT and no OAuth bearer. Every mutation uses X-Nimo-CSRF-Token; membership is revalidated on each request, and logout or rotation revokes the previous session.
| Method | Route | Input / headers | Result |
|---|---|---|---|
| POST | /ai/internal/bff/session | Origin; { username, password, companyId } | BFF cookie and { csrfToken, expiresAt, user }; bad credentials: 401 |
| POST | /ai/internal/bff/session/bootstrap | Cookie + Origin | Renews the CSRF token for the session; invalid/expired/replayed session: 401 |
| POST | /ai/internal/bff/session/rotate | Cookie + Origin + X-Nimo-CSRF-Token | Rotates the opaque session; the previous one is revoked |
| POST | /ai/internal/bff/session/logout | Cookie + Origin + X-Nimo-CSRF-Token | Revokes the session and clears the cookie; 204 |
| POST | /ai/internal/bff/promotions/environments/:environmentId | Cookie + Origin + X-Nimo-CSRF-Token; promotion payload | 201: same promotion service with live OWNER/ADMIN revalidation |
The BFF is a first-party browser boundary. A client that already holds an OWNER/ADMIN's credentials can still authenticate against the ordinary API routes; the promotion endpoint with a direct USER JWT stays denied.
DSL projects require either their own definition or a platform definition followed by the company. For platform definitions only the exact currently followed version can be pinned. No session: 401; revoked permission or external token: 403; someone else's, nonexistent or unauthorized project/definition/version: 404; invalid input: 400. Denied operations leave no partial writes.
The operations above require a platform JWT and a live OWNER/ADMIN role. Runtime sessions are restricted to an explicit allowlist of DSL execution routes and methods; the guard denies them on administrative endpoints, including @Public() routes. Every request revalidates membership, application role, release, expiry/revocation and the exact registered origin. The context is derived from the session and header selectors cannot change it. CORS reflects active origins for browser transport but grants no authority. This capability stays internal and is not added to the public SDK, external MCP or the embeddable chat.
Publishing another DSL version changes no releases and deploys nothing. A release is not edited; creating another one keeps the previous. currentRelease starts at null. Connections are stored as opaque references to existing providers in immutable revisions; credentials stay in the vault. Only production payment/Stripe and email/SMTP may reference active tenant providers. Preview uses no productive credentials and falls back to no built-in platform provider; without a sandbox adapter it returns a 422 diagnostic and does not execute the effect. Push and webhook stay blocked until approved adapters exist. The DSL runtime uses the authorized environment as the namespace for instances and relationships: preview and production share no data. Received IDs are accepted only after verifying membership, project ownership and the assigned release. The file namespace is still pending.
In Git, the SHA is a declarative reference: the repository is not queried or verified yet, nothing is built and nothing is deployed. repositoryBindingId is rejected until repositories are integrated and authorized. toolchain.snapshotSchemaVersion describes the capture format, not an executed build.
Promotion requires a live OWNER/ADMIN session and Preview's active release with a confirmed successful deployment. It verifies the configuration revision and the tenant provider references, creates an immutable assignment in Production and switches the active release in a transaction with generation control. It keeps the previous assignments. The confirmation indicates backend runtime activation; it does not deploy to Pages nor check Production's remote health. sourceHash, artifactHash and configurationHash describe the source snapshot, the compiled bytes and the private configuration revision, respectively.