ModelForge-Public/docs/operations/PROJECT_ONBOARDING.md

Project onboarding and service credentials

Open Projects with a personal operator or administrator key.

1. Create a project with a stable slug, name, description, owner, environment and optional labels.
2. Add an exact versioned capability requirement. Select reindex support for incompatible embedding spaces, or schema migration support when required. The requirement uses the stable gateway route.
3. As administrator, issue a service identity for one explicit binding. Choose a unique client name, purpose and expiry. The binding fixes its capability and workload priority.
4. Save the returned key in the consumer's secret store or a protected token file. It appears once and the Console hides it after 60 seconds. The database retains a digest, never plaintext.
5. Expand the integration examples. Set the gateway origin, token-file location and capability in the consumer environment. The examples never contain the issued key.
6. Paste the service key into the memory-only test field and run Check connectivity. This verifies its exact scope without starting inference. The key must belong to the selected identity.
7. Supply non-sensitive capability-specific JSON and run Run capability check. This executes one real gateway request and may load the governed deployment. Image/audio templates require real base64 input; placeholder strings cannot produce a successful test.

The workspace shows blockers, deployment health, current key expiry, last use and the successful gateway request ID. Readiness requires current key/current deployment evidence from the last 24 hours. Rotation, a deployment change, expiry, revocation or stale evidence invalidates the relevant checks. Production eligibility is deliberately not inferred; use the project-fit and lifecycle approval workflows. A fresh installation with no eligible stable deployment stays visibly blocked.

Rotation and revocation

Choose immediate replacement, 15 minutes, one hour or 24 hours of overlap. Both the expected credential ID and the replacement expiry are sent to the API. Refresh after a conflict. The old key expires no later than its original expiry or the overlap deadline; another rotation ends any older overlap. Replacement keys are also revealed once.

Revoke all keys shows the client, capability and last use. Type the exact client name and acknowledge the interruption. Current and overlapping keys immediately stop authorizing new requests. Already admitted work may finish. A revoked identity cannot be revived through rotation; issue a new service identity if access is needed again. Historical metadata remains auditable.

Legacy single-key rotate/delete routes remain available for compatible automation and use immediate revocation; they also use the same transactional claim. New integrations should use the guarded plural /credentials/rotate and /credentials/revoke routes.

API surface

Route	Authority	Result
GET /api/v1/project-workspace and /{key}	Viewer	Persisted requirements, safe client metadata, observed readiness
POST /api/v1/project-workspace	Operator	Persist project identity/owner/environment/labels with audit
POST /api/v1/project-workspace/{key}/requirements	Operator	Bind an exact compatible requirement with audit
POST /api/v1/admin/service-clients	Admin	Issue key once; accepts explicit project_binding_id
GET /api/v1/admin/service-clients/{id}/credentials	Admin	Most recent 100 key metadata records, never digests/plaintext
POST /api/v1/admin/service-clients/{id}/credentials/rotate	Admin	Expected credential ID, overlap seconds and new UTC-aware expiry
POST /api/v1/admin/service-clients/{id}/credentials/revoke	Admin	Expected credential ID and exact client-name confirmation
GET /api/v1/capabilities/{capability}/check	Scoped service key	Connectivity, client identity and correlation ID; no inference

Connectivity checks exist for the five implemented embedding, reranking, OCR, vision and transcription capability routes. Human keys cannot authenticate there, and service keys cannot open the Console. Protected control-plane responses use Cache-Control: no-store.

Migration 20260908_0026 adds onboarding metadata and credential supersession. Restore the verified pre-migration backup if rollback is necessary after new history exists; do not drop that history. See verification and clients.