Platform API

Create a browser session

Exchange a server API key for a short-lived, organization-bound browser token.

POSThttps://app.mindbill.org/partner/v2/browser-sessions

Use one authenticated route for connected post-submit lifecycle UI, or when a browser client needs an explicitly granted public operation without exposing the permanent API key.

AuthenticationBearer server API key

Permissions by credentialServer API key only

IdempotencyRequired for safe retries

This endpoint requires a server API key and is unavailable to browser sessions. See the component API inventory for exact paths and SDK methods.

Request body

FieldTypeDescription

subjectRequired

string

Stable identifier for the signed-in user in your system.

allowedOriginRequired

string

Exact browser origin. Paths, query strings, fragments, and credentials are rejected.

HTTPS; HTTP loopback allowed in sandbox

permissionsRequired

MindBillBrowserPermission[]

Role-derived grants: bills:create/read/act, documents:read, payers:read, eors:read, organization:manage, team:manage, rfas:read/create/edit/act/sign, and autofill:run. autofill:run requires explicit operator delegation from autofill:write, an enabled reportAutofill organization capability, and an organization-wide session. team:manage must be explicitly requested and delegated from orgs:team:write; organization:manage does not grant team access. Grant only the actions the authenticated host user may perform; RFA access requires an organization-wide session and treatmentBilling.

resource.billId

string

Optional least-privilege restriction to one existing bill. Cannot be combined with bills:create.

expiresIn

number

Session lifetime in seconds.

Integer 60–3600

Examples

import { MindBillClient } from "@mindbill/node";

const mindbill = new MindBillClient({
  apiKey: process.env.MINDBILL_API_KEY!,
});

export async function POST(request: Request) {
  const user = await requireSignedInUser(request);
  const permissions = permissionsForRole(user.role);

  const session = await mindbill.createBrowserSession({
    subject: user.id,
    allowedOrigin: process.env.APP_ORIGIN!,
    permissions,
    expiresIn: 900,
  });

  return Response.json(session);
}

curl https://app.mindbill.org/partner/v2/browser-sessions \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: session_user_42" \
  --data '{
    "subject": "user_42",
    "allowedOrigin": "https://your-product.example",
    "permissions": ["bills:create", "bills:read", "documents:read", "payers:read"]
  }'

Response

201 Created

{
  "sessionId": "session_01J6Z8",
  "organizationId": "org_01J4",
  "subject": "user_42",
  "permissions": ["bills:create", "bills:read", "documents:read", "payers:read"],
  "resource": null,
  "token": "mb_browser_…",
  "expiresAt": "2026-08-29T19:15:00.000Z"
}

FieldTypeDescription

sessionIdRequired

string

Session audit identifier.

organizationIdRequired

string

Organization fixed by the server credential.

subjectRequired

string

Your signed-in user identifier.

permissionsRequired

string[]

Effective browser permissions.

resourceRequired

{ billId: string } | null

Optional bill restriction.

tokenRequired

string

Short-lived browser bearer token.

expiresAtRequired

string

ISO expiration timestamp.