Sessions

Short-lived tokens for end-user apps.

The `Session` object

Attributes

id required Type: string
token required Type: string
Shown once.
expires_at required Type: string
max_checks required Type: integer
subject_reference required Type: string

The Session object

{
  "id": "ses_01j9x3m8v7k2q4r5s6t7u8v9w0",
  "token": "unf_ses_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2026-09-25T10:20:30Z",
  "max_checks": 1,
  "subject_reference": "cust-88"
}

Create a client session token

POST /nib/sessions

Needs nib:checks:create: Submit checks, sessions, live

For end-user apps: one subject, one streamed check. The token is shown once.

Request body

SessionCreate

subject_reference required Type: Id
scope required Type: "check"[]
ttl_seconds optional Type: integer
max_checks optional Type: 1

Returns

201 Type: Session
Created
400 Type: Problem
invalid_request, invalid_version, idempotency_key_required or invalid_signature
401 Type: Problem
unauthorized
402 Type: Problem
billing_required
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

POST /nib/sessions · curl

curl -X POST "https://api.unforged.sh/nib/sessions" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{
  "subject_reference": "cust-88",
  "scope": [
    "check"
  ],
  "ttl_seconds": 300
}'

POST /nib/sessions · Python

import requests

r = requests.post(
    "https://api.unforged.sh/nib/sessions",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
    json={
        "subject_reference": "cust-88",
        "scope": [
            "check"
        ],
        "ttl_seconds": 300
    },
)
print(r.json())

POST /nib/sessions · Node.js

const res = await fetch('https://api.unforged.sh/nib/sessions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "subject_reference": "cust-88",
    "scope": [
      "check"
    ],
    "ttl_seconds": 300
  }),
});
console.log(await res.json());

Response 201

{
  "id": "ses_01j9x3m8v7k2q4r5s6t7u8v9w0",
  "token": "unf_ses_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2026-09-25T10:20:30Z",
  "max_checks": 1,
  "subject_reference": "cust-88"
}

Revoke a session

DELETE /nib/sessions/{session_id}

Needs nib:checks:create: Submit checks, sessions, live

204 even if already revoked; its live connections close.

Parameters

session_id pathrequired Type: string

Returns

204
Done
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

DELETE /nib/sessions/{session_id} · curl

curl -X DELETE "https://api.unforged.sh/nib/sessions/{session_id}" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

DELETE /nib/sessions/{session_id} · Python

import requests

r = requests.delete(
    "https://api.unforged.sh/nib/sessions/{session_id}",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

DELETE /nib/sessions/{session_id} · Node.js

const res = await fetch('https://api.unforged.sh/nib/sessions/{session_id}', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());