Refresh

Get a new access token using a refresh token.

When to use: When the access token expires and you need a new one without re-authenticating.

Prerequisites

• Completed Login

• Have a refresh token from authentication

5-Line Core

result = await gateway.refresh_session(
    refresh_token=token.refresh_token,
    organization_id="default",
)
new_token = result.unwrap()

When to Refresh

Situation	Action
Access token expired	Call refresh_session()
API returns 401	Call refresh_session()
Proactively before expiry	Call refresh_session()
Refresh token expired	User must login again

Step-by-Step

1

Check Token Expiry

# AuthToken has an is_expired property
if token.is_expired:
    print("Token expired, need to refresh")

2

Refresh the Token

result = await gateway.refresh_session(
    refresh_token=token.refresh_token,
    organization_id="default",
)

3

Use New Token

if result.is_ok:
    new_token = result.unwrap()
    print(f"New access token: {new_token.access_token[:20]}...")
else:
    print("Refresh failed, user must login again")

4

Expected Output

New access token: eyJhbGciOiJIUzI1N...

You can refresh tokens!

Complete Example

Create refresh.py:

"""GL IAM Token Refresh Example."""

import asyncio

from gl_iam import IAMGateway
from gl_iam.core.types import PasswordCredentials
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)

    # Login to get tokens
    auth_result = await gateway.authenticate(
        credentials=PasswordCredentials(email="[e-mail]", password="SecurePass123"),
        organization_id="default",
    )
    user, token = auth_result.unwrap()
    print(f"Original token: {token.access_token[:30]}...")

    # Refresh the token
    result = await gateway.refresh_session(
        refresh_token=token.refresh_token,
        organization_id="default",
    )

    if result.is_ok:
        new_token = result.unwrap()
        print(f"New token: {new_token.access_token[:30]}...")
        print("Token refreshed successfully!")
    else:
        print(f"Refresh failed: {result.error.message}")

    await provider.close()


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

Run it:

uv run refresh.py

Expected output:

Original token: eyJhbGciOiJIUzI1NiIsInR5cCI6...
New token: eyJhbGciOiJIUzI1NiIsInR5cCI6...
Token refreshed successfully!

Common Pitfalls

Pitfall	Solution
Storing refresh token in frontend	Keep refresh tokens server-side only
Not handling refresh failure	Redirect user to login on failure
Refreshing too late	Refresh proactively before expiry

Next Steps

• Logout - End the session

• Validate - Verify the new token works

---

Found an issue on this page? Report it on our feedback form.