Authentication

SkyState has four auth modes at the HTTP layer:

• Developer bearer tokens - minted by the hosted developer login flow. They carry skystate_role=developer and skystate_account_id.
• End-user bearer tokens - minted by the hosted end-user login flow. They carry skystate_role=end_user, skystate_account_id, skystate_project_id, skystate_environment, and user_id.
• API keys - project-scoped credentials sent as Authorization: ApiKey <sky_...>.
• Anonymous requests - no auth header, used only on explicitly anonymous routes.

Firebase ID tokens are accepted only by POST /v1/auth/authorize as login proof. They are not accepted as product-route bearer tokens.

Auth Exchange Endpoints

Method	Route	Request	Response/behavior
POST	/v1/auth/authorize/start	JSON body with flow or mode, redirectUri, state, codeChallenge, codeChallengeMethod; end-user flow also uses accountId, projectId, environment	Creates an authorization session and returns authorizationSessionId and expiresIn.
GET	/v1/auth/authorize/context?txn=<session>	query txn	Returns hosted-login context: flow, optional project branding, and allowed providers.
POST	/v1/auth/authorize	form body with authorizationSessionId and firebaseIdToken	Completes hosted login and redirects to the registered redirect URI with code and state, or renders an error page.
POST	/v1/auth/token	JSON body with mode, code, codeVerifier, redirectUri; end-user mode also requires accountId and projectId	Exchanges code for idToken, refreshToken, and expiresIn.
POST	/v1/auth/refresh	JSON body with mode and refreshToken	Rotates refresh tokens. Reuse of a superseded token revokes the token family and returns 401.
POST	/v1/auth/logout	JSON body with refreshToken	Revokes the refresh token family and returns 204.
GET	/v1/auth/dev/cli-code?code=<code>&state=<state>	query code, optional state	Renders the developer CLI code page.
GET	/v1/auth/dev/cli-code/status?code=<code>	query code	Returns pending while the exchange code exists, then consumed.

Developer Flow

1. A client starts a session with POST /v1/auth/authorize/start and flow=developer.
2. Auth-front signs the developer in with Firebase and form-posts to POST /v1/auth/authorize.
3. The API redirects to the registered redirect URI with code and state.
4. The client exchanges the code at POST /v1/auth/token with mode=developer.
5. Product routes use Authorization: Bearer <idToken>.

Developer tokens whose account no longer exists are rejected during bearer validation.

End-User Flow

End-user auth uses the same exchange endpoints with flow=end_user / mode=end_user. The session is scoped to accountId, projectId, and environment.

End-user state routes require token scope to match the route project and environment.

Hosted Auth Runtime Config

The hosted login page can read public project auth settings through:

GET /v1/readonly/{accountId}/projects/{projectId}/auth/end-user/config

The response includes enabled status, project branding, and allowed identity providers for the hosted end-user auth surface.