# Create a portal session (/docs/api-reference/hooks-portal/create-hook-portal-session)

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.

`POST https://api.coss.com/v1/hooks/applications/{application}/portal_sessions`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Path parameters

- `application` (string, required): The application's `id` (`happ_…`) or your `uid` for it.

## Request body

- `expires_in` (integer, 60-86400): Seconds until it expires: default 3600, at most 86400.
- `read_only` (boolean): The user can look but not change anything.

## Example request

TypeScript (the `coss` package):

```ts
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,
});
```

HTTP:

```sh
curl -X POST "https://api.coss.com/v1/hooks/applications/customer_8812/portal_sessions" \
  -H "Authorization: Bearer $COSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_in": 3600
}'
```

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.hooks.portal.create_session(
    application="customer_8812",
    expires_in=3600,
)
```

Go:

```go
import (
	"context"

	coss "github.com/cosscom/coss-go"
	cossclient "github.com/cosscom/coss-go/client"
	hooks "github.com/cosscom/coss-go/hooks"
)

client := cossclient.NewClient() // option.WithAPIKey(…) or COSS_API_KEY

request := &hooks.CreateHookPortalSessionRequest{
    Application: "customer_8812",
    ExpiresIn: coss.Int(
        3600,
    ),
}
client.Hooks.Portal.CreateSession(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

client = Coss::Client.new # api_key: or COSS_API_KEY

client.hooks.portal.create_session(
  application: "customer_8812",
  expires_in: 3600
)
```

PHP:

```php
<?php

use Coss\Coss;
use Coss\Hooks\Portal\Requests\CreateHookPortalSessionRequest;

$client = new Coss(); // apiKey: or COSS_API_KEY

$client->hooks->portal->createSession(
    'customer_8812',
    new CreateHookPortalSessionRequest([
        'expiresIn' => 3600,
    ]),
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.hooks.portal.requests.CreateHookPortalSessionRequest;

Coss client = Coss.builder().build(); // .apiKey(…) or COSS_API_KEY

client.hooks().portal().createSession(
    "customer_8812",
    CreateHookPortalSessionRequest
        .builder()
        .expiresIn(3600)
        .build()
);
```

.NET:

```csharp
using Coss;
using Coss.Hooks;

var client = new CossClient(); // apiKey: or COSS_API_KEY

await client.Hooks.Portal.CreateSessionAsync(
    new CreateHookPortalSessionRequest { Application = "customer_8812", ExpiresIn = 3600 }
);
```

## Response 200

The session, with its URL.

- `object` ("hook_portal_session", required)
- `id` (string, required)
- `application_id` (string, required): The id of the application this session manages.
- `url` (string, required): 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, required): The secret part of `url`, shown only here.
- `read_only` (boolean, required): Whether the user can only look.
- `expires_at` (string, required, date-time): When the session stops working.

Example:

```json
{
  "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"
}
```

## Errors

- `400`: The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `404`: No application with this id or uid exists in the API key's environment (`application_not_found`).
- `413`: The request body is larger than 5 MB (`payload_too_large`).
- `415`: The body is not sent as `application/json` (`unsupported_media_type`).
- `422`: The body failed validation (`validation_error`).
- `429`: Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: The portal isn't available yet (`portal_unavailable`).