62 lines
4.4 KiB
Markdown
62 lines
4.4 KiB
Markdown
# 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](../quality/RC02_PROJECT_VERIFICATION.md) and [clients](../../clients/README.md).
|