# ContextStellar Authentication and Onboarding

## Anonymous access

The editor's prompt analysis is local and free without signup. Public documentation, OpenAPI and educational pages can be fetched without credentials. The displayed waitlist count is public, but a zero count may be a dependency fallback. This is not an anonymous cloud scoring API.

## Browser sessions

Sign in through /sign-in using Clerk. Browser API calls use the existing cookie session; do not add bearer-token handling to the web app. Management permissions come from the local organization/project membership records, not merely from being signed in.

Creating a project needs an existing organization with an owner/admin membership. Issuing or revoking keys, editing policies and reordering context require project owner/admin permissions. Project deletion requires owner permissions. Personal-data export/deletion is scoped to the signed-in user.

## Project keys

In an existing project, an owner/admin can create a key through dashboard Settings. The secret is returned only at creation and only a hash is stored. Current generated keys carry ingest/read scopes.

```sh
curl "$CONTEXTSTELLAR_URL/api/v1/traces?limit=5" \
  -H "Authorization: Bearer $CONTEXTSTELLAR_API_KEY"
```

Read-scoped keys can query traces and hook metrics. Ingest-scoped keys can send event batches and Claude Code hooks. Keys do not grant management privileges or access to other projects.

Self-serve key creation does not imply automatic organization provisioning. If you have no organization or project, ask the operator or your administrator. No dedicated hosted sandbox is currently advertised; use an explicitly approved test project.

## OAuth status and proposed next step

This application does not currently accept OAuth access tokens or advertise an OAuth authorization server. Do not substitute the Google social-login flow for delegated API authorization.

Clerk supports OAuth applications, authorization-code flows with S256 PKCE, consent and authorization-server discovery. A future integration should use the existing managed provider rather than invent a token server. Before enabling it, the operator must approve client registration/redirect policies, consent behavior, API scopes and mapping to local project membership. Provider identity scopes alone must never grant cross-project telemetry access. Prefer explicitly registered clients initially; do not enable unauthenticated dynamic registration without a separate security decision.

After approved configuration, the API must validate issuer, audience, expiry and granted permissions, enforce existing tenant authorization, and verify the complete consent/token/revocation flow before publishing discovery metadata. See [Clerk's implementation guide](https://clerk.com/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth). No placeholder metadata endpoint is published here.

## Handling denial

Read the HTTP status and JSON hint. Do not rotate through tenant IDs on 403/404. Treat keys and cookies as secrets. If you report a problem, include the operation, status and time, not credentials or private prompt contents.
