Skip to main content

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:

StepDescription
EmailOperator supplies their email address to the platform
POST console.k9o.io/api/discovery/orgsPlatform 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 switcherIf the email belongs to more than one org, the operator selects the target org
AuthOperator authenticates against the selected org's configured IdP (password, SSO, magic link, etc.)
Console landingPost-auth, operator lands at <orgSlug>.console.k9o.io/
Project Selection InterstitialPost-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 contextOperator 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": "[email protected]"
}

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:

StateMeaningIncluded by default
accessibleOperator has membership; can enter immediatelyYes
lockedOperator can see the project exists but cannot enter; access request availableYes (surfaced with lock UI)
hiddenOperator has no visibility; project is not returnedNever

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)
StateTerminalWho can transition
pendingNoAdmins (→ granted/denied); author (→ cancelled); platform TTL daemon (→ expired)
grantedYes—
deniedYes—
expiredYes—
cancelledYes—

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:

EventTrigger
data.write.access_request.createdAccess request submitted (POST /projects/<slug>/access-requests)
data.write.access_request.grantedAdmin grants the request
data.write.access_request.deniedAdmin denies the request
data.write.access_request.expiredPlatform TTL daemon expires a pending request after 7 days
data.write.access_request.cancelledAuthor 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 orgSlug and projectSlug resolve.
  • 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.