coss.comdocs

Create a portal session

POST
/v1/hooks/applications/{application}/portal_sessions

Signs the application's user in to the portal, where they add endpoints, pick event types, see deliveries and retry them, without you building any UI. Create one each time the user opens it (from your backend: never expose the API key) and open or embed the returned url; embedding needs the site's origin in the environment's portal settings.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Path Parameters

application*string

The application's id (happ_…) or your uid for it.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
expires_in?integer

Seconds until it expires: default 3600, at most 86400.

Range60 <= value <= 86400
read_only?boolean

The user can look but not change anything.

Response Body

The session, with its URL.

application/json
  1. response
object*"hook_portal_session"
Value in"hook_portal_session"
id*string
application_id*string
url*string

Open it or embed it in an iframe (from an allowed origin). The token is in the URL fragment, so it never reaches a server log: hand the URL only to that application's user.

token*string

The secret part of url, shown only here.

read_only*boolean
expires_at*string
Formatdate-time
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.hooks.portal.createSession({  application: "customer_8812",  expires_in: 3600,});
{  "object": "hook_portal_session",  "id": "hps_01k7c8m4q2f3e9v6t5r1n0p8yz",  "application_id": "happ_01k7c8m4q2f3e9v6t5r1n0p8yz",  "url": "https://portal.example/s/hps_01k7c8m4q2f3e9v6t5r1n0p8yz#cossp_…",  "token": "cossp_…",  "read_only": false,  "expires_at": "2026-01-15T10:30:00.000Z"}