pub struct AuthApi { /* private fields */ }Expand description
User registration and OTP authentication
Implementations§
Source§impl AuthApi
impl AuthApi
Sourcepub async fn apple_native_auth(
&self,
body: &AppleNativeAuthRequest,
) -> Result<AppleNativeAuthResponse>
pub async fn apple_native_auth( &self, body: &AppleNativeAuthRequest, ) -> Result<AppleNativeAuthResponse>
Sign in with Apple — native iOS handshake
iOS drives the Apple authorization sheet via ASAuthorizationController and POSTs the
resulting identity_token (Apple-signed JWT, RS256) here. Server fetches Apple JWKS (cached
24h), verifies signature/iss/aud/exp, extracts sub + email, then mints a session. The
email is only present on first login — subsequent logins reuse the stored
apple_sub_to_email mapping. is_private_email (@privaterelay.appleid.com) is honoured:
relay address is stored as the canonical email.
POST /api/v1/auth/oauth/apple/native
Sourcepub async fn complete_o_auth_login(
&self,
provider: &OAuthLoginProviderConfigStatusProvider,
params: &CompleteOAuthLoginParams,
) -> Result<CompleteOAuthLoginResponse>
pub async fn complete_o_auth_login( &self, provider: &OAuthLoginProviderConfigStatusProvider, params: &CompleteOAuthLoginParams, ) -> Result<CompleteOAuthLoginResponse>
OAuth callback — exchange code, mint session
Provider redirects here. Server validates state (one-shot, 10 min TTL, provider-bound),
exchanges code for tokens, fetches verified email + IdP sub, then mints a session via
the shared post-verify path. On success: 302 to ${return_to}#api_key=...&email=... if a
return_to was stored, else JSON {api_key, email}. Refuses to mint for super-admin email
(Guideline-style separation: super-admin must use OTP).
GET /api/v1/auth/oauth/{provider}/callback
Sourcepub async fn disable_mfa(&self) -> Result<DisableMfaResponse>
pub async fn disable_mfa(&self) -> Result<DisableMfaResponse>
Remove MFA enrolment for the calling user
POST /api/v1/auth/mfa/disable
Sourcepub async fn enrol_mfa(&self, body: &EnrolMfaRequest) -> Result<MfaEnrolment>
pub async fn enrol_mfa(&self, body: &EnrolMfaRequest) -> Result<MfaEnrolment>
Begin MFA enrolment
Returns the TOTP secret (otpauth URL + base32 secret) and one-time recovery codes. Recovery
codes are shown ONCE and never re-readable; user must store them. Optional body: { label?, issuer?, algorithm? }.
POST /api/v1/auth/mfa/enrol
Sourcepub async fn exchange_o_auth_app_code(
&self,
body: &OAuthAppExchangeRequest,
) -> Result<OAuthAppExchangeResponse>
pub async fn exchange_o_auth_app_code( &self, body: &OAuthAppExchangeRequest, ) -> Result<OAuthAppExchangeResponse>
Trade a mobile hand-off code for the session
Second half of the mobile sign-in hand-off. When start is called with
app_code_challenge, the callback redirects to the app with #code= instead of
#api_key=, and the key is only released here, to a caller that presents the matching
verifier. Single-use and short-lived: the code is consumed on the first attempt, successful
or not.
POST /api/v1/auth/oauth/exchange
Sourcepub async fn get_me(&self) -> Result<GetMeResponse>
pub async fn get_me(&self) -> Result<GetMeResponse>
Get the calling user + tenant context
Single source of truth for the browser to render account state, role badges, and the tenant
header. Resolves the user via api-key.user_id, then JWT sub claim, then
tenant_primary_email lookup.
Read role from the top level, never from user.role. The top-level field is required
and always present; it resolves as user?.role ?? extractRole(auth), so it answers for
every caller. user is nullable and NOT required — it is null whenever the caller
authenticated with an api key rather than a signed-in session, and the nested role exists
only in the other case.
Spelled out because the schema alone did not prevent it: two mobile clients independently
modelled the response as {user, tenant}, read user.role, and so could not tell an owner
from a viewer for any key-authed caller — one of them had gated no settings on role at all
as a result. A client tested only against a JWT session sees user.role work perfectly and
ships. scopes and auth_method are required for the same reason and answer for every
caller too.
GET /api/v1/me
Sourcepub async fn get_mfa_status(&self) -> Result<GetMfaStatusResponse>
pub async fn get_mfa_status(&self) -> Result<GetMfaStatusResponse>
MFA enrolment status for the calling user
GET /api/v1/auth/mfa/status
Sourcepub async fn google_one_tap_auth(
&self,
body: &GoogleOneTapAuthRequest,
) -> Result<GoogleOneTapAuthResponse>
pub async fn google_one_tap_auth( &self, body: &GoogleOneTapAuthRequest, ) -> Result<GoogleOneTapAuthResponse>
Sign in with Google — One Tap (FedCM) credential exchange
The browser-side Google Identity Services (GSI) script renders a FedCM One Tap prompt on
/login and POSTs the resulting credential (a Google-signed JWT, RS256) here. Server
fetches Google JWKS (cached 24h), verifies signature/iss/aud/exp against the configured
Google OAuth client_id from admin KV, extracts sub + email, then mints a session via the
shared post-verify path. Same session shape the /oauth/google/callback redirect flow
returns.
POST /api/v1/auth/oauth/google/onetap
Sourcepub async fn list_auth_providers(&self) -> Result<ListAuthProvidersResponse>
pub async fn list_auth_providers(&self) -> Result<ListAuthProvidersResponse>
List linked OAuth identity providers + OTP fallback
Returns one entry per supported login method (otp, github, google, apple) with
linked: true|false. Used by the Settings UI to render link/unlink buttons.
GET /api/v1/me/auth-providers
Sourcepub async fn list_me_sessions(&self) -> Result<ListMeSessionsResponse>
pub async fn list_me_sessions(&self) -> Result<ListMeSessionsResponse>
List active api_keys (devices) for the calling user
Returns the user’s active api_keys across all devices (browser, iOS, CLI). is_current
flags the key making this call so UI can highlight ‘this device’. Sorted by last_used_at
desc.
GET /api/v1/me/sessions
Sourcepub async fn list_o_auth_login_providers(
&self,
) -> Result<OAuthLoginProvidersList>
pub async fn list_o_auth_login_providers( &self, ) -> Result<OAuthLoginProvidersList>
List OAuth identity providers (for login UI)
Public, IP-rate-limited (60/min). Returns the list of configured OAuth login providers with
their enabled status — UI uses this to render only the buttons that will work. apple is
always advertised as enabled (App Store Guideline 4.8 placement requirement);
github/google enabled depends on whether super-admin has provisioned
client_id+client_secret.
GET /api/v1/auth/oauth/providers
Sourcepub async fn logout(&self) -> Result<LogoutResponse>
pub async fn logout(&self) -> Result<LogoutResponse>
Revoke the calling api_key
Revokes the api_key used to make this call. Idempotent — re-call returns 200 with
already_revoked: true. Cookie/JWT-only sessions return {ok: true, key_id: null} since
there’s no server-side key to revoke.
POST /api/v1/auth/logout
Sourcepub async fn mint_sse_token(&self) -> Result<MintSSETokenResponse>
pub async fn mint_sse_token(&self) -> Result<MintSSETokenResponse>
Mint a 60-second SSE token scoped to events:read
Mints a short-lived (60 s) API key carrying only events:read scope, for use as the
?token= query param on browser SSE/WebSocket subscriptions which cannot set Authorization
headers. Token does not appear in the tenant key dashboard and auto-purges from KV.
POST /api/v1/auth/sse-tokens
Sourcepub async fn register(
&self,
body: &Map<String, Value>,
) -> Result<Map<String, Value>>
pub async fn register( &self, body: &Map<String, Value>, ) -> Result<Map<String, Value>>
Register new user
POST /api/v1/register
Sourcepub async fn request_otp_code(
&self,
body: &Map<String, Value>,
) -> Result<Map<String, Value>>
pub async fn request_otp_code( &self, body: &Map<String, Value>, ) -> Result<Map<String, Value>>
Request OTP code
POST /api/v1/auth/request-code
Sourcepub async fn revoke_me_session(
&self,
key_id: &str,
) -> Result<RevokeMeSessionResponse>
pub async fn revoke_me_session( &self, key_id: &str, ) -> Result<RevokeMeSessionResponse>
Revoke a specific device session
Revokes one of the user’s api_keys. Refuses to revoke another user’s key (403). Idempotent —
re-revoking a revoked key returns {ok: true, already_revoked: true}.
DELETE /api/v1/me/sessions/{keyId}
Sourcepub async fn start_o_auth_login(
&self,
provider: &OAuthLoginProviderConfigStatusProvider,
params: &StartOAuthLoginParams,
) -> Result<Value>
pub async fn start_o_auth_login( &self, provider: &OAuthLoginProviderConfigStatusProvider, params: &StartOAuthLoginParams, ) -> Result<Value>
Begin browser OAuth login (302 to provider)
Redirects the browser to GitHub/Google authorize URL. Server stores a one-shot state record
(10 min TTL) keyed by the state query the provider will echo back. PKCE codeVerifier is
generated server-side. return_to defaults to nothing (response is JSON); when set, must
satisfy the allow-list (same-origin paths, configured Universal-Link hosts, or snaga://).
device_label is captured here and surfaces on the minted api_key for /me/sessions.
GET /api/v1/auth/oauth/{provider}/start
Sourcepub async fn unlink_auth_provider(
&self,
provider: &OAuthLoginProviderItemId,
) -> Result<UnlinkAuthProviderResponse>
pub async fn unlink_auth_provider( &self, provider: &OAuthLoginProviderItemId, ) -> Result<UnlinkAuthProviderResponse>
Unlink an OAuth provider from the user
Refuses to drop the user’s last sign-in factor (counts other linked providers + OTP recovery
email). Idempotent — unlinking an already-unlinked provider returns 200 with
already_unlinked: true.
DELETE /api/v1/me/auth-providers/{provider}
Sourcepub async fn verify_email(&self) -> Result<Map<String, Value>>
pub async fn verify_email(&self) -> Result<Map<String, Value>>
Verify email link
GET /api/v1/verify-email
Sourcepub async fn verify_mfa(
&self,
body: &VerifyMfaRequest,
) -> Result<VerifyMfaResponse>
pub async fn verify_mfa( &self, body: &VerifyMfaRequest, ) -> Result<VerifyMfaResponse>
Verify a TOTP code
Used both during enrolment confirmation and on subsequent logins. Burns no recovery code;
for recovery use /auth/mfa/recovery.
POST /api/v1/auth/mfa/verify
Sourcepub async fn verify_mfa_recovery(
&self,
body: &VerifyMfaRecoveryRequest,
) -> Result<VerifyMfaRecoveryResponse>
pub async fn verify_mfa_recovery( &self, body: &VerifyMfaRecoveryRequest, ) -> Result<VerifyMfaRecoveryResponse>
Verify a one-time recovery code (burns it on success)
POST /api/v1/auth/mfa/recovery
Sourcepub async fn verify_otp_code(
&self,
body: &AuthVerifyCodeRequest,
) -> Result<AuthVerifyCodeResponse>
pub async fn verify_otp_code( &self, body: &AuthVerifyCodeRequest, ) -> Result<AuthVerifyCodeResponse>
Verify OTP code
Expects body with email and code only (no request_id). Returns api_key to use as Bearer token.
POST /api/v1/auth/verify-code