Result Pattern

Handle GL IAM errors using the unified Result pattern.

When to use: GL IAM Gateway operations return a Result - learn to handle success and errors consistently.

Architecture Note

GL IAM uses a hybrid error handling approach:

Layer	Pattern	Rationale
IAMGateway (public API)	Result Pattern	Type-safe, explicit error handling for consumers
Providers (internal)	Exceptions	Simpler implementation, idiomatic Python

The Gateway wraps provider exceptions into Results, giving you the best of both worlds: clean Result-based APIs for your code, while providers use natural Python exception handling internally.

Prerequisites

• Completed Login

• Basic understanding of error handling

5-Line Core

result = await gateway.authenticate(credentials, organization_id="default")
if result.is_ok:
    user, token = result.unwrap()
else:
    print(f"Error: {result.error.code}")

Result States

State	Check	Access
Success	result.is_ok	result.value or result.unwrap()
Error	result.is_err	result.error
MFA Required	result.requires_mfa	result.mfa_challenge_id

Step-by-Step

1

Check Success

result = await gateway.authenticate(credentials, organization_id="default")

if result.is_ok:
    user, token = result.unwrap()
    print(f"Welcome, {user.email}!")

2

Handle Errors

if result.is_err:
    error = result.error
    print(f"Code: {error.code}")
    print(f"Message: {error.message}")

3

Pattern Match Errors

from gl_iam.core.types.result import ErrorCode

if result.is_err:
    match result.error.code:
        case ErrorCode.AUTHENTICATION_FAILED:
            print("Invalid credentials")
        case ErrorCode.ACCOUNT_LOCKED:
            print("Account locked")
        case _:
            print(f"Error: {result.error.message}")

4

Handle MFA

if result.requires_mfa:
    challenge_id = result.mfa_challenge_id
    print(f"MFA required: {challenge_id}")

5

Expected Output

Welcome, [e-mail]!

Or on error:

Code: ErrorCode.AUTHENTICATION_FAILED
Message: Invalid credentials

You can handle Results!

Complete Example

Create result_pattern.py:

"""GL IAM Result Pattern Example."""

import asyncio

from gl_iam import IAMGateway
from gl_iam.core.types import PasswordCredentials
from gl_iam.core.types.result import ErrorCode
from gl_iam.providers.postgresql import PostgreSQLProvider, PostgreSQLConfig

DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost:5432/gliam"


async def main():
    # Setup
    config = PostgreSQLConfig(database_url=DATABASE_URL)
    provider = PostgreSQLProvider(config)
    gateway = IAMGateway.from_fullstack_provider(provider)

    # Success case
    print("--- Success Case ---")
    result = await gateway.authenticate(
        credentials=PasswordCredentials(email="[e-mail]", password="SecurePass123"),
        organization_id="default",
    )

    if result.is_ok:
        user, token = result.unwrap()
        print(f"✓ Logged in as: {user.email}")

    # Error case
    print("\n--- Error Case ---")
    result = await gateway.authenticate(
        credentials=PasswordCredentials(email="[e-mail]", password="wrong"),
        organization_id="default",
    )

    if result.is_err:
        match result.error.code:
            case ErrorCode.AUTHENTICATION_FAILED:
                print("✗ Invalid credentials")
            case ErrorCode.ACCOUNT_LOCKED:
                print("✗ Account locked")
            case _:
                print(f"✗ Error: {result.error.message}")

    # Using unwrap_or for defaults
    print("\n--- Default Value ---")
    result = await gateway.get_user("nonexistent", organization_id="default")
    user = result.unwrap_or(None)
    print(f"User: {user}")  # None

    await provider.close()


if __name__ == "__main__":
    asyncio.run(main())

Run it:

uv run result_pattern.py

Expected output:

--- Success Case ---
✓ Logged in as: [e-mail]

--- Error Case ---
✗ Invalid credentials

--- Default Value ---
User: None

Error Codes Reference

Category	Codes
Auth	AUTHENTICATION_FAILED, INVALID_CREDENTIALS, ACCOUNT_LOCKED
Token	INVALID_TOKEN, SESSION_EXPIRED, SESSION_NOT_FOUND
User	USER_NOT_FOUND, USER_ALREADY_EXISTS
Config	NO_AUTH_PROVIDER, NO_USER_STORE, NO_SESSION_PROVIDER

FastAPI Integration

from fastapi import HTTPException
from gl_iam.core.types.result import ErrorCode

def error_to_status(code: ErrorCode) -> int:
    return {
        ErrorCode.AUTHENTICATION_FAILED: 401,
        ErrorCode.INVALID_TOKEN: 401,
        ErrorCode.PERMISSION_DENIED: 403,
        ErrorCode.USER_NOT_FOUND: 404,
        ErrorCode.USER_ALREADY_EXISTS: 409,
    }.get(code, 400)

@app.post("/login")
async def login(email: str, password: str):
    result = await gateway.authenticate(
        credentials=PasswordCredentials(email=email, password=password),
        organization_id="default",
    )

    if result.is_ok:
        user, token = result.unwrap()
        return {"token": token.access_token}

    raise HTTPException(
        status_code=error_to_status(result.error.code),
        detail=result.error.message,
    )

Common Pitfalls

Pitfall	Solution
Calling unwrap() without checking	Always check is_ok first
Ignoring MFA state	Check requires_mfa for auth results
Generic error handling	Pattern match on error codes