docs: enhance auth module documentation and type hints

[maslinedwin]

Improves auth module with comprehensive documentation, type hints, and examples.

[semgrep-code-scan]

Semgrep identified a blocking 🔴 issue in your code:
The domain xai.com is owned by a Chinese company and not xAI. Please use the proper x.ai domain.

Why this might be safe to ignore:

The matched code 'api.xai.com' is in a docstring example comment for the xAI SDK, and 'api.xai.com' appears to be the correct API endpoint for xAI's service (not a mistaken reference to the unrelated xai.com Chinese company domain). The rule is overly broad, matching any occurrence of 'xai.com' including valid subdomains like 'api.xai.com' which is the legitimate xAI API endpoint.

To resolve this comment:

🔧 No guidance has been designated for this issue. Fix according to your organization's approved methods.

💬 Ignore this finding

Reply with Semgrep commands to ignore this finding.

• /fp <comment> for false positive
• /ar <comment> for acceptable risk
• /other <comment> for all other reasons

Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by xai-incorrect-domain.

_{You can view more details about this finding in the Semgrep AppSec Platform.}