Common Control Plane API

Common is the control plane for identity, tenancy, directory, and infrastructure lifecycle.

Core endpoint families

• auth and session: /v1/auth/*, /v1/me, /v1/me/preferences
• user lifecycle: /v1/users*, home-tenant conversion
• tenant governance: /v1/tenants*, invites, members, groups, guest invites
• routing and directory: /v1/directory/resolve, /v1/directory/repo/{repo_id}
• snapshots: entitlement and authz snapshot endpoints
• infra lifecycle: /v1/infrastructures*, infra tokens
• repo registry and placement: /v1/repos*

When to call Common

Use Common when your question is about:

• who the user is
• which tenant or repo they belong to
• which SynckHub infra owns a repo
• which admin workflow should create, invite, route, or move something

Do not call Common as a substitute for normal repository reads and writes.

Integration practice

• use OpenAPI (common-control-plane/docs/openapi/v1.yaml) for generated client contracts
• treat Common as source of truth for routing and home-tenant decisions
• do not assume control-plane availability for every data-plane request

Common mistakes

• storing guessed repo routing instead of resolving it
• assuming tenant roles alone tell you current repo access
• coupling hot-path repository UX to control-plane round trips