Portal Sessions

Portal sessions provide temporary, scoped access to the Developer Portal for your end users. Create a session to generate a one-time URL your customers can use to manage their webhook endpoints, subscriptions, and delivery history.

API path: POST /management/v1/workspaces/{workspaceId}/applications/{appId}/portal

Portal sessions require an application ID — the session is scoped to that application's endpoints.

Options

Parameter	Type	Default	Description
`role`	string	`editor`	Session permissions: `admin` (full CRUD), `editor` (create/update, no delete), `viewer` (read-only).
`expiresInMinutes`	integer	`60`	Session lifetime in minutes (1–60).
`metadata`	object	—	Flat key-value metadata (max 10 keys). Automatically attached to endpoints created during the session. Useful for tracking which of your users created the endpoint.

Response

Field	Type	Description
`url`	string	One-time URL to redirect your end user to.
`code`	string	Short-lived session code embedded in the URL.
`expiresAt`	string	ISO 8601 timestamp when the session expires.

Create a portal session

curl -X POST https://api.nahook.com/management/v1/workspaces/ws_abc/applications/app_123/portal \
  -H "Authorization: Bearer nhm_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor",
    "expiresInMinutes": 30,
    "metadata": {
      "userId": "usr_456",
      "email": "[email protected]"
    }
  }'

const session = await mgmt.portalSessions.create("ws_abc", "app_123", {
  role: "editor",
  expiresInMinutes: 30,
  metadata: { userId: "usr_456", email: "[email protected]" },
});
// session.url -> "https://portal.nahook.com/..."
// session.expiresAt -> "2024-01-15T12:30:00Z"

session = mgmt.portal_sessions.create(
    "ws_abc", "app_123",
    role="editor",
    expires_in_minutes=30,
    metadata={"userId": "usr_456", "email": "[email protected]"},
)
# session["url"] -> "https://portal.nahook.com/..."

session, _ := mgmt.PortalSessions.Create(ctx, "ws_abc", "app_123",
    &nahook.CreatePortalSessionOptions{
        Metadata:         map[string]string{"userId": "usr_456", "email": "[email protected]"},
        Role:             "editor",
        ExpiresInMinutes: 30,
    })
// session.URL -> "https://portal.nahook.com/..."

var session = mgmt.portalSessions().create("ws_abc", "app_123",
    new CreatePortalSessionOptions(
        Map.of("userId", "usr_456", "email", "[email protected]"),
        "editor",
        30));
// session.getUrl() -> "https://portal.nahook.com/..."

var session = await mgmt.PortalSessions.CreateAsync("ws_abc", "app_123",
    new CreatePortalSessionOptions {
        Role = "editor",
        ExpiresInMinutes = 30,
        Metadata = new() { ["userId"] = "usr_456", ["email"] = "[email protected]" },
    });
// session.Url -> "https://portal.nahook.com/..."

$session = $mgmt->portalSessions->create("ws_abc", "app_123", [
    "role" => "editor",
    "expiresInMinutes" => 30,
    "metadata" => ["userId" => "usr_456", "email" => "[email protected]"],
]);
// $session["url"] -> "https://portal.nahook.com/..."

session = mgmt.portal_sessions.create(
  "ws_abc", "app_123",
  role: "editor",
  expires_in_minutes: 30,
  metadata: { "userId" => "usr_456", "email" => "[email protected]" },
)
# session["url"] -> "https://portal.nahook.com/..."

let session = mgmt.portal_sessions().create("ws_abc", "app_123",
    Some(CreatePortalSessionOptions {
        role: Some("editor".into()),
        expires_in_minutes: Some(30),
        metadata: Some(HashMap::from([
            ("userId".into(), "usr_456".into()),
            ("email".into(), "[email protected]".into()),
        ])),
    })).await?;
// session.url -> "https://portal.nahook.com/..."

Minimal session

All options are optional. Omit them to get a session with the default editor role, a 60-minute expiry, and no metadata.

curl -X POST https://api.nahook.com/management/v1/workspaces/ws_abc/applications/app_123/portal \
  -H "Authorization: Bearer nhm_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

const session = await mgmt.portalSessions.create("ws_abc", "app_123");
// session.url -> "https://portal.nahook.com/..."

session = mgmt.portal_sessions.create("ws_abc", "app_123")
# session["url"] -> "https://portal.nahook.com/..."

session, _ := mgmt.PortalSessions.Create(ctx, "ws_abc", "app_123", nil)

var session = mgmt.portalSessions().create("ws_abc", "app_123");

var session = await mgmt.PortalSessions.CreateAsync("ws_abc", "app_123");

$session = $mgmt->portalSessions->create("ws_abc", "app_123", []);

session = mgmt.portal_sessions.create("ws_abc", "app_123")

let session = mgmt.portal_sessions().create("ws_abc", "app_123", None).await?;

Portal URLs are single-use. Once a URL is opened, it cannot be reused. Generate a new session for each user visit.

Next steps

Developer Portal Overview — understand the portal experience
Embedding the Portal — embed the portal in your app
Portal Permissions — role-based access control