Project Selection & Access Requests
After an operator authenticates against an org's IdP, the platform presents a Project Selection Interstitial — a gated step that resolves which project the operator lands in. This page covers the full lifecycle from email discovery to project selection, the endpoints that drive it, and the access-request resource for operators who need access to a project they cannot currently see. It is grounded in identity chapter §10 (anonymous discovery) and §11 (project selection + access requests).
1. Auth-flow lifecycle
Email → POST console.k9o.io/api/discovery/orgs → Org switcher (n>1)
→ Auth (per org IdP) → <orgSlug>.console.k9o.io/
→ Project Selection Interstitial (GET /projects) → /@<projectSlug>/<mode>
Each step:
| Step | Description |
|---|---|
| Operator supplies their email address to the platform | |
POST console.k9o.io/api/discovery/orgs | Platform returns the list of orgs associated with the email. This is Step 1 of anonymous discovery; an optional Step 2 (POST console.k9o.io/api/discovery/projects) narrows to the projects within a chosen org the email holds grants on, both served from the pre-authentication discovery namespace. |
| Org switcher | If the email belongs to more than one org, the operator selects the target org |
| Auth | Operator authenticates against the selected org's configured IdP (password, SSO, magic link, etc.) |
| Console landing | Post-auth, operator lands at <orgSlug>.console.k9o.io/ |
| Project Selection Interstitial | Post-authentication, the platform resolves which projects the operator can access via GET <orgSlug>.api.k9o.io/projects; operator selects or is auto-skipped to their last project |
| Project context | Operator lands at /@<projectSlug>/<mode> inside the selected project |
Identity is org-bound; project is post-authentication context. The Project Selection Interstitial replaces the prior pattern that dropped operators directly into a project switcher before authentication — that pattern was semantically incorrect, since an operator's identity resolves against an org, not a project.
1.1 Auto-skip
If the operator is a member of exactly one project and has previously visited it, the interstitial auto-skips and the operator lands directly at /@<projectSlug>/<mode>. The localStorage-persisted last-project preference drives the skip; no round-trip required.
2. Endpoints
2.1 POST console.k9o.io/api/discovery/orgs — Org discovery (Step 1)
Host: console.k9o.io (platform-level discovery namespace; pre-authentication, no org subdomain)
Auth: anonymous — no Authorization header, no JWT. The endpoint is rate-limited and constant-time by design (see §2.1.1).
Request:
{
}
Email match is exact-only — no substring matching — as an anti-enumeration measure. A malformed address returns K9O_INVALID_REQUEST_SHAPE (400, context.field: "email").
Response: the list of orgs associated with the email. Each entry carries the org slug, display name, consoleDomain (the fully-qualified Console host to navigate to post-sign-in — <slug>.console.k9o.io by default, or the org's configured custom domain), and the matched account class (operator or end_user) that drives sign-in-endpoint dispatch. Results are capped at 10 with a truncated flag.
An optional Step 2 — POST console.k9o.io/api/discovery/projects — narrows to the projects within a chosen org the email holds grants on. Both steps live in the pre-authentication discovery namespace and keep each call's exposure surface narrow: Step 1 never reveals third-party orgs, Step 2 never reveals projects the email has no grant on.
2.1.1 Anti-enumeration posture
A miss (email matches no org) and a hidden match (email matches, but no org has discovery enabled) return an identical empty response — there is no distinguishable "no orgs" versus "all orgs hidden" signal. The response is constant-time to close the existence-leak-via-timing channel.
2.2 GET /projects — List projects
Host: <orgSlug>.api.k9o.io (tenant-scoped; requires a valid tenant session)
Query: ?include=accessible (default) | ?include=locked | omit for all visible
Three-state visibility per project:
| State | Meaning | Included by default |
|---|---|---|
| accessible | Operator has membership; can enter immediately | Yes |
| locked | Operator can see the project exists but cannot enter; access request available | Yes (surfaced with lock UI) |
| hidden | Operator has no visibility; project is not returned | Never |
2.3 POST /projects/<projectSlug>/access-requests — Submit access request
Host: <orgSlug>.api.k9o.io
Request:
{
"reason": "Need access for onboarding review",
"requestedRole": "PROJECT_EDITOR"
}
Both fields are optional; reason is capped at 200 characters and requestedRole names the project role the operator is asking for. Submitting creates an access request in pending state with a 7-day TTL. A caller who already holds a role on the target project is rejected with K9O_ROLE_ALREADY_GRANTED (409) — the submit surface is for non-members only.
2.4 GET /access-requests — List access requests
Host: <orgSlug>.api.k9o.io
Query: ?status=pending | ?status=granted | ?status=denied | ?status=expired | ?status=cancelled | omit for all
Response is RLS-scoped: requesting operators see only their own access requests; project admins see all requests for their projects.
2.5 POST /access-requests/<arq_id>/grant and .../deny — Admin actions
Host: <orgSlug>.api.k9o.io
Required role: PROJECT_ADMIN on the target project, or ORG_ADMIN where an org-policy override permits it.
grant takes { role, decisionReason? } — the approver names the role materialised, which need not equal the requestedRole the operator asked for. It atomically grants the requesting operator membership and transitions the access request to granted; there is no observable state in which the request is granted but the role has not been materialised. deny takes { decisionReason? } and transitions to denied with no role change. An arq_id that does not resolve to a request the caller can see returns K9O_ACCESS_REQUEST_NOT_FOUND (404).
2.6 DELETE /access-requests/<arq_id> — Author cancel
Host: <orgSlug>.api.k9o.io
Author-only. Cancels a pending access request, transitioning it to cancelled. Not available to admins via this endpoint (use deny).
3. Access-request lifecycle
The access-request resource follows a five-state closed enum:
pending → granted
→ denied
→ expired (7-day TTL)
→ cancelled (author-only)
| State | Terminal | Who can transition |
|---|---|---|
pending | No | Admins (→ granted/denied); author (→ cancelled); platform TTL daemon (→ expired) |
granted | Yes | — |
denied | Yes | — |
expired | Yes | — |
cancelled | Yes | — |
TTL: 7 days.
GC: Terminal access requests (granted / denied / expired / cancelled) are retained for 90 days post-terminal for audit purposes, then garbage-collected.
Grant atomicity: The platform executes org-membership materialisation and access-request state transition inside a single transaction. A granted access request is always accompanied by an active role. There is no window in which the request is marked granted but the operator cannot access the project.
4. Audit-event family
Five audit events are emitted into the audit ledger per ch05 §4.2, standard envelope:
| Event | Trigger |
|---|---|
data.write.access_request.created | Access request submitted (POST /projects/<slug>/access-requests) |
data.write.access_request.granted | Admin grants the request |
data.write.access_request.denied | Admin denies the request |
data.write.access_request.expired | Platform TTL daemon expires a pending request after 7 days |
data.write.access_request.cancelled | Author cancels their own pending request |
All five events include the standard audit-envelope fields (actor, timestamp, resource ID, org context) per the error catalogue audit-event schema.
5. See also
- Session Model — the exchange flow and tenant session that the post-auth project selection step builds on.
- Routing Modes — the canonical URL grammar that
/@<projectSlug>/<mode>composes against. - Slug Addressing — how
orgSlugandprojectSlugresolve. - Custom Domains — custom-domain capability of every project; session model and project selection carry through.
- Identity-Aware Kernel — the RBAC role taxonomy that governs which projects are visible to which operators.