Principal Sessions

Generate session tokens for end-users to view and manage their agent permissions.

Overview

The principal_sessions sub-client lets you create short-lived session tokens for your end-users. These tokens power the Permission Dashboard where users can view which agents have access and revoke grants.

session = grantex.principal_sessions.create(
    CreatePrincipalSessionParams(
        principal_id="user_abc123",
        expires_in="2h",
    )
)

# Send session.dashboard_url to the user
print(session.dashboard_url)

---

principal_sessions.create()

Create a session token for an end-user. Returns a URL they can open to manage their permissions.

from grantex import Grantex, CreatePrincipalSessionParams

grantex = Grantex(api_key="your-api-key")

session = grantex.principal_sessions.create(
    CreatePrincipalSessionParams(
        principal_id="user_abc123",
        expires_in="2h",
    )
)

print(session.session_token)   # JWT string
print(session.dashboard_url)   # Full URL with embedded token
print(session.expires_at)      # '2026-03-01T14:00:00.000Z'

Parameters: CreatePrincipalSessionParams

principal_id · str · required

The end-user’s principal ID — the same user_id used in grantex.authorize().

expires_in · str | None

Session duration. Format: "30m", "1h", "24h". Defaults to "1h", capped at "24h".

Response: PrincipalSessionResponse

session_token · str

The signed JWT session token.

dashboard_url · str

Full URL the user can open in their browser to view and revoke permissions.

expires_at · str

ISO 8601 timestamp when the session token expires.

Errors

Status	Code	Cause
400	BAD_REQUEST	Missing principal_id or invalid expires_in format
404	NOT_FOUND	No active grants exist for this principal