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:
- Insert your local row.
POSTyour product origin endpoint on the Control Plane (path from your capability descriptor).- Persist the returned
platformProjectId. - 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
| Step | Symptom | Fix |
|---|---|---|
| A | 403 | User is not a member |
| C | Duplicate Collections | Origin not idempotent — reuse ids |
| D | 401 | Missing actor header |