client.auth

client.auth — the auth operations.

On AsyncKindgi every method is the same, awaited.

client.auth.login()

login(
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> AuthorizationResponse

Initiate OAuth/OIDC login. POST /v1/auth/login/{providerId}

Framework generates state + PKCE code_verifier (S256 challenge). Caller redirects the user-agent to authorizationUrl. Provider redirects back to redirectUri with code + state; caller POSTs those to /v1/auth/callback/:providerId to complete the flow. When the provider config populated allowedRedirectUris, the effective redirect_uri MUST be an exact match — otherwise 400 redirect-uri-not-allowed.

client.auth.callback()

callback(*, timeout: float | None = None, **fields: Any) -> CallbackResult

Complete an OAuth/OIDC callback. POST /v1/auth/callback/{providerId}

Public — the caller has not yet obtained a session token. Verifies state, exchanges code for provider tokens via the deployment's exchangeCode, fetches userinfo, and persists a session via SessionStoreBinding. Returns an opaque kgi_sk_* session token the caller uses on subsequent requests. The underlying provider access-token never leaves the server. When the provider config populated allowedRedirectUris, the stored redirect_uri is re-checked against the current allowlist — a mismatch (allowlist tightened between login and callback) returns 400 redirect-uri-mismatch.

client.auth.refresh()

refresh(
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> RefreshResult

Refresh the current session token. POST /v1/auth/refresh

Requires a session token (kgi_sk_*); bearer tokens are managed via /v1/tokens. When the deployment wired a refreshToken callback and the provider issued a refresh token, provider tokens rotate too; otherwise only the framework session token rotates. OAuth 2.1 BCP refresh-token rotation: the OLD session token is invalidated (marked rotated) — reusing it after refresh returns 401 refresh-token-invalid so compliant clients can retry with the fresh token instead of prompting a re-auth.

client.auth.logout()

logout(
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> LogoutResult

Revoke the current session. POST /v1/auth/logout

Requires a session token (kgi_sk_*); bearer tokens are managed via /v1/tokens. Idempotent — revoking an already-revoked session returns { revoked: false }.