api.auth.login

Exchange credentials for a TokenPair. If the account has MFA active, the response is an mfa_required challenge instead. Feed it to auth.mfa.verify.

When the response is tokens, the pair is automatically persisted to the configured tokenStore, with no tokens.save(res) boilerplate.

const res = await api.auth.login("alice@example.com", "hunter22!hunter22");
 
if (res.status === "tokens") {
  // Tokens are already in the store: fire requests.
} else {
  // res.challenge_id → punt to the MFA verify step.
}

Returns: Promise<LoginResponse> (discriminated union, see Auth → Types).

Throws: ApiError with status: 401 on bad credentials.

REST endpoint: POST /auth/login.