Zum Hauptinhalt springen

Recipe — onboard a Collection

End-to-end happy path you can rehearse on staging. Replace placeholders; never commit secrets.

Ingredients​

export PLEXON_BASE="https://plexon-v3.projects-a.plygrnd.tech"
export PLEXON_SERVICE_SECRET="…"
export PLEXON_USER_ID="…" # member who should see the Collection
export PLATFORM_PROJECT_ID="…" # existing Collection id, if you already have one

A) Discover what the viewer can open​

curl -sS "${PLEXON_BASE}/api/platform/provisioning/accessible-collections" \
-H "X-Service-Secret: ${PLEXON_SERVICE_SECRET}" \
-H "X-Plexon-Contract-Version: 2026-05-plexon-federation-v3" \
-H "X-Plexon-User-Id: ${PLEXON_USER_ID}"

Pass: HTTP 200.
Fail usefully: 401 → fix auth (Auth); empty list → invite the user or pick another actor.

B) TypeScript variant (BFF)​

import {
AccessibleCollectionsResponseSchema,
buildFederationHeaders,
FEDERATION_CONTRACT_VERSION,
} from '@chbrdk/plexon-federation'

export async function listCollections(viewerUserId: string) {
const res = await fetch(
`${process.env.PLEXON_BASE}/api/platform/provisioning/accessible-collections`,
{
headers: buildFederationHeaders({
contractVersion: FEDERATION_CONTRACT_VERSION,
serviceSecret: process.env.PLEXON_SERVICE_SECRET!,
userId: viewerUserId,
}),
},
)
if (!res.ok) throw new Error(`accessible-collections ${res.status}`)
return AccessibleCollectionsResponseSchema.parse(await res.json())
}

C) Product-first create (origin)​

When the user creates inside your UI:

  1. Insert your local row.
  2. POST your product origin endpoint on the Control Plane (path from your capability descriptor).
  3. Persist the returned platformProjectId.
  4. Be ready for upsert retries from DIC to your product URL.

Validate bodies with the SDK origin / upsert Zod schemas — do not guess JSON shapes.

D) GraphQL sanity check​

curl -sS -X POST "${PLEXON_BASE}/api/graphql" \
-H 'content-type: application/json' \
-H "X-Service-Secret: ${PLEXON_SERVICE_SECRET}" \
-H 'X-Plexon-Contract-Version: 2026-05-plexon-federation-v3' \
-H "X-Plexon-User-Id: ${PLEXON_USER_ID}" \
-d '{"query":"query Me { me { id email } }"}'

Checklist​

  • Viewer lists Collections
  • Origin or upsert linked your product row to platformProjectId
  • UI opens the Collection without inventing a second project type
  • Revoke still works afterwards

What usually goes wrong​

StepSymptomFix
A403User is not a member
CDuplicate CollectionsOrigin not idempotent — reuse ids
D401Missing actor header