portal

Customer Portal

An Institflow account that owns a tenant managing its licence view, install command, registry credentials and relay statement — read-only except for minting the same install token/registry credential a console operator could. Cloud/control-plane only: answers 404 on a self-hosted install.

8 נקודות קצה

GET `/api/v1/portal/institute`

The owned institute: licence state/expiry, install state, subscription plan, and the relay balance. Read-only.

דורש אימותהרשאהללא הרשאה נוספת

דוגמה עם curl

curl

curl -X GET "https://your-institute.example/api/v1/portal/institute" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200The institute.

שם	סוג	מגבלות
tenantחובה	object	—
licenseחובה	object \| null	—
addressחובה	string \| null	—
installחובה	object \| null	—
subscriptionחובה	object \| null	—
relayחובה	object	—

json

{
  "tenant": {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "slug": "string",
    "name": "Algebra I",
    "status": "active"
  },
  "license": {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
    "jti": "string",
    "issuedAt": "2026-03-02T09:00:00.000Z",
    "expiresAt": "2026-03-02T09:00:00.000Z",
    "lastValidatedAt": "2026-03-02T09:00:00.000Z",
    "status": "valid",
    "metadata": {},
    "createdAt": "2026-03-02T09:00:00.000Z",
    "updatedAt": "2026-03-02T09:00:00.000Z"
  },
  "address": "string",
  "install": {
    "installId": "2472867d-2472-7472-8728-2472867d2472",
    "appVersion": "string",
    "state": "provisioning",
    "lastSeenAt": "2026-03-02T09:00:00.000Z",
    "updateChannel": "stable",
    "updaterLastResult": "up_to_date",
    "updaterLastReason": "none",
    "needsAdoption": true,
    "adoptionCommands": [
      "value"
    ]
  },
  "subscription": {
    "planCode": "string",
    "planName": "string",
    "status": "trialing",
    "currentPeriodEnd": "2026-03-02T09:00:00.000Z"
  },
  "relay": {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
    "balanceUnits": -9007199254740991,
    "overdraftUnits": -9007199254740991,
    "status": "active",
    "ratePerMinute": -9007199254740991,
    "ratePerDay": -9007199254740991,
    "reputationHold": true,
    "reputationHoldReason": "string",
    "senderDisplayName": "string",
    "senderNameApprovedAt": "2026-03-02T09:00:00.000Z",
    "senderNameRequestedAt": "2026-03-02T09:00:00.000Z",
    "createdAt": "2026-03-02T09:00:00.000Z",
    "updatedAt": "2026-03-02T09:00:00.000Z",
    "spend30dUnits": -9007199254740991,
    "installCount": -9007199254740991,
    "pendingInstallCount": -9007199254740991
  }
}

400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST `/api/v1/portal/institute/install-command`

Generate a one-time install command for the owned institute. The raw token is returned exactly once.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שם	סוג	מגבלות
label	string	1–200 chars

דוגמה

json

{
  "label": "string"
}

דוגמה עם curl

curl

curl -X POST "https://your-institute.example/api/v1/portal/institute/install-command" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "label": "string"
  }'

תשובות

201The new token and its ready-to-paste install command.

שם	סוג	מגבלות
tokenחובה	object	—
rawTokenחובה	string	—
commandחובה	string	—

json

{
  "token": {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
    "state": "unused",
    "expiresAt": "2026-03-02T09:00:00.000Z",
    "usedAt": "2026-03-02T09:00:00.000Z",
    "usedFromIp": "string",
    "revokedAt": "2026-03-02T09:00:00.000Z",
    "createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
    "createdByAccountId": "34bcf5dc-34bc-74bc-8bcf-34bcf5dc34bc",
    "label": "string",
    "createdAt": "2026-03-02T09:00:00.000Z",
    "updatedAt": "2026-03-02T09:00:00.000Z"
  },
  "rawToken": "string",
  "command": "string"
}