Platform API

Create a management session

Mint a one-time sign-in URL that opens the hosted MindBill billing workspace for your organization.

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

Use behind the prebuilt Billing-management button (or your own link) so organization staff can open the full MindBill work queue, reports, and denials without a second login. This is a hosted-SSO handoff, not a browser API token.

AuthenticationBearer server API key

Permissions by credentialServer: management:write

IdempotencyNot required

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. Recorded for audit; never rendered in the product.

role

"biller" | "viewer"

Access level for the managed sign-in. biller covers day-to-day billing operations; viewer is read-only.

Defaults to biller; admin is never available

expiresIn

number

Seconds until the unopened link expires.

Integer 60–900; defaults to 300

Examples

export async function POST(request: Request) {
  const user = await requireSignedInUser(request); // your existing auth

  const response = await fetch(
    "https://app.mindbill.org/partner/v2/management-sessions",
    {
      method: "POST",
      headers: {
        authorization: `Bearer ${process.env.MINDBILL_API_KEY!}`,
        "content-type": "application/json",
      },
      body: JSON.stringify({ subject: user.id, role: "biller" }),
    },
  );
  const session = await response.json();

  return Response.json({ url: session.url });
}

curl https://app.mindbill.org/partner/v2/management-sessions \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "user_42",
    "role": "biller"
  }'

Response

201 Created

{
  "url": "https://app.mindbill.org/partner/management-signin?token=mbms_…",
  "expiresAt": "2026-09-02T19:05:00.000Z",
  "organizationId": "org_01J4",
  "subject": "user_42",
  "role": "biller"
}

FieldTypeDescription

urlRequired

string

One-time sign-in URL. Open it in a new tab; it works exactly once.

expiresAtRequired

string

ISO expiration timestamp for the unopened link.

organizationIdRequired

string

Organization fixed by the server credential.

subjectRequired

string

Your signed-in user identifier.

roleRequired

string

Effective managed role.