Principal Sessions

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. The session token is carried in the URL fragment (#session=...), not the query string, so it is never transmitted to the server or captured in Referer headers or access logs.

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

Overview

Authorization

Resources

Enforcement

Reference

Principal Sessions

Overview

principal_sessions.create()

Parameters: `CreatePrincipalSessionParams`

Response: `PrincipalSessionResponse`

Errors

​Overview

​principal_sessions.create()

​Parameters: CreatePrincipalSessionParams

​Response: PrincipalSessionResponse

​Errors

Overview

principal_sessions.create()

Parameters: `CreatePrincipalSessionParams`

Response: `PrincipalSessionResponse`

Errors