stable · guide · 0.1.0

Sandbox Quick Start

This is the complete public sandbox onboarding path.

Sandbox request

Before starting, obtain four organization-owned inputs: the Platform Operations request-channel URL, the accountable Platform Operator's name, the approved secret-manager destination, and an organization-approved GitHub identity with read access to https://github.com/q10242/MiniCenter. MiniCenter cannot choose these organization-specific systems. If any input is missing, stop; do not substitute a public issue, chat, email, or a personal password manager.

In that request channel, send the accountable Operator the Project Client name, sandbox environment, exact HTTPS redirect URIs, Realtime browser origins, minimum scopes from the capability matrix, expected peak request/concurrent-connection volume, and the approved secret-manager destination. The Operator records the accepted sandbox quotas or the reason for a capacity exception. Record the request URL/ID, requester, approver, environment and intended evidence. A request never activates production.

Choose stable raw HTTP or a beta SDK

所有 SDK 都是薄 transport client；依 Project Backend 的語言選擇即可：

The stable integration path is the complete machine-readable OpenAPI JSON; rendered API pages link each operation from its capability domain. SDK and CLI examples are executable beta source-acceptance artifacts, not claims that ecosystem packages or release binaries have been published. Their source checkout may require the approved GitHub access requested above. Production activation using an SDK requires its separately reviewed ecosystem artifact; until then, use raw HTTP from the OpenAPI contract. Record the SDK version and repository commit used for sandbox acceptance.

Obtain a sandbox Project Credential

Approval and Project Client registration

The maintainer submits the approved name, sandbox environment, exact redirects/origins, complete scope set, accepted quotas, and request record. Registration and initial secret issuance are Operator-only: an authorized Platform Operator verifies the approval and registers the Project Client with every approved scope; there is no later scope-update step. The Operator assigns named maintainers Project Console Access at /project; maintainers receive the resulting Project Client ID, environment, masked configuration and accepted quotas there, not access to an Operator API.

A separately authorized Operator issues a Credential for that exact Project Client with only the capability scopes needed by the runtime. Include clients:read when it must perform the first identity request. One Operator may perform registration and issuance only when separately authorized for both responsibilities and the Project Client. These privileged operations are intentionally absent from public Project Backend OpenAPI; maintainers request them rather than receiving a Platform Session or Operator authority.

The Operator verifies the requested environment, redirect allowlist, scopes, quotas, and browser origins against the approved request. Project Console must show the same Project Client and sandbox environment before the secret is delivered.

One-time Credential delivery

第二個 operation 只回傳一次 Project Credential plaintext。Operator 必須把它寫入 sandbox request 指定的 approved secret-manager destination，並只授權 request 中列名的 maintainers；不得貼進 issue、聊天、email 或瀏覽器。Maintainer在同一 request record 記錄 secret-manager item ID（不得記 plaintext）與 receipt timestamp，然後設定：

Environment setup pseudocode（請自行替換 secret）：

export MINICENTER_URL=https://sandbox.minicenter.otus.tw
export MINICENTER_PROJECT_CREDENTIAL='paste-the-one-time-sandbox-secret-here'
export MINICENTER_CORRELATION_ID='generate-one-uuid-for-this-acceptance-request'

這三行是 pseudocode，不由 CI 執行，也不要提交到 repository。瀏覽器不應取得 Project Credential。

Make the first request

選一個與 Project Backend 相符的 executable example：

• TypeScript MiniCenterClient.request
• Python Client.request
• PHP Client::request
• Go Client.Do
• CLI minicenter request

成功結果會包含 Project Client 的 id、name、environment 與 scopes。

這些範例只從 Project Backend 或本機 shell 發送請求；公開文件沒有 browser-based request executor。

For a minimal black-box acceptance adapter, use the public minicenter/reference-project-backend package. Its README defines the transport boundary and lastEvidence() returns the actual status plus caller-owned correlation ID. It uses the same OpenAPI paths as raw HTTP and the official SDKs, and contains no MiniCenter application dependency.

Validate approved capabilities

For every requested capability, follow its matrix link and OpenAPI contract, then capture the HTTP status, stable operation or event ID, caller-supplied correlation ID, and expected sandbox-provider outcome. A successful first GET /project-client is HTTP 200; each SDK example shows how to supply and record its correlation ID. Confirm retries reuse the same idempotency key and that reads or events reconcile an uncertain write. A capability that is not selected remains unconfigured and untested.

For OIDC, complete Project Backend OIDC. For existing users, complete Hosted Identity Migration. For browser Realtime, use the official browser transport; never expose the Project Credential.

Credential rotation and revocation

A maintainer with assigned Project Console Access opens /project, selects the exact sandbox Project Client/environment, confirms Issue replacement, and writes the one-time value directly to the request's approved secret-manager destination. Switch every sandbox runtime and prove it works while the old Credential remains active. After logs show no old use, the same authorized maintainer explicitly confirms Revoke for the old masked credential. Prove the old value returns 401 while the replacement succeeds. Record credential IDs and timestamps, never plaintext. Initial registration and initial Credential issuance remain Operator-only.

Acceptance evidence

The maintainer provides: approved request; Project Client ID and environment; configured redirects, origins, scopes and quotas; SDK and contract versions; first-request correlation ID; per-capability results; negative authorization and retry evidence; rotation/revocation evidence; and every clarification request. Treat each undocumented clarification as a documentation defect before acceptance.

Production activation handoff

Sandbox acceptance does not create or enable a production Project Client. Open a new record in the same organization-provided Platform Operations request channel, addressed to the named accountable Operator, containing the accepted evidence, production redirects/origins, capacity and provider review, secret-manager destination/owner, rollout and rollback plan. Platform Operations must approve and execute that later gate; the maintainer must not reuse the sandbox Credential or infer activation from this checklist.