End-User Permission Dashboard

​

How It Works

1. Developer generates a session URL — Your backend calls POST /v1/principal-sessions with the user’s principalId and gets back a short-lived session token embedded in a URL.
2. You share the URL with the user — Via email, in-app notification, settings page link, etc.
3. User opens the dashboard — They see all agents with active access, scopes granted, and a revoke button for each.
4. User revokes access — One click revokes the grant and cascade-revokes any delegated sub-grants.

​

Generate a Session URL

​

Using curl

curl -X POST https://api.grantex.dev/v1/principal-sessions \
  -H "Authorization: Bearer $GRANTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"principalId": "user_abc123", "expiresIn": "2h"}'

{
  "sessionToken": "eyJhbGciOiJSUzI1NiIs...",
  "dashboardUrl": "https://api.grantex.dev/permissions#session=eyJhbGciOiJSUzI1NiIs...",
  "expiresAt": "2026-03-01T14:00:00.000Z"
}

​

Using the TypeScript SDK

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const session = await grantex.principalSessions.create({
  principalId: 'user_abc123',
  expiresIn: '2h',   // optional, defaults to "1h", max "24h"
});

console.log(session.dashboardUrl);
// → "https://api.grantex.dev/permissions#session=eyJ..."
// The session token is in the URL fragment (#), not the query string,
// so it is never transmitted to the server or leaked via Referer headers.

// Send this URL to your user (email, in-app, etc.)

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",   # optional, defaults to "1h", max "24h"
    )
)

print(session.dashboard_url)
# → "https://api.grantex.dev/permissions#session=eyJ..."
# The session token is in the URL fragment (#), not the query string,
# so it is never transmitted to the server or leaked via Referer headers.

​

Parameters

​

Response

​

What the User Sees

• Apps with access — A card for each agent with an active grant, showing the agent name, description, granted scopes, issue date, expiry date, and a “Revoke access” button.
• Recent activity — A table of recent audit log entries for actions taken by agents on their behalf.
• Session expired — If the session token has expired, a clear message asking them to request a new link.

​

Revoking Access

1. The grant is marked as revoked
2. All delegated sub-grants (child grants from agent-to-agent delegation) are also revoked
3. Redis revocation keys are set so tokens are rejected immediately
4. A grant.revoked webhook event is fired

​

Security Considerations

• Short-lived tokens — Session tokens default to 1 hour. Use the shortest duration practical for your use case.
• Scoped access — Session tokens are bound to a specific principal+developer pair. A user cannot see or revoke another user’s grants, and cannot see grants from other developers.
• Purpose claim — Session JWTs include a purpose: "principal_dashboard" claim that prevents grant tokens from being reused as session tokens (and vice versa).
• No API key exposure — End-users never see or need the developer’s API key.
• HTTPS only — Always serve dashboard URLs over HTTPS in production.

​

API Endpoints