Admin API

Administrative endpoints for managing organization-level settings, external integrations, and operational infrastructure. Most procedures require elevated permissions (org_owner, tenant_admin, or site_admin roles).

Billing

Read-only billing information and plan enforcement. Stripe integration handles checkout sessions and payment methods.

Plan hierarchy: free → starter → pro → enterprise

Endpoints

`GET /api/v1/admin/billing/subscription`

Get the current organization’s subscription plan and Stripe subscription information.

tRPC: billing.getSubscription Auth: Bearer token required (scope: read:items) or session cookie. Role: org_owner only. Org context: Required

Response:

{
  "plan": "pro",
  "status": "active",
  "stripeCustomerId": "cus_xxx",
  "stripeSubscriptionId": "sub_xxx",
  "currentPeriodEnd": "2026-05-01T00:00:00.000Z",
  "limits": {
    "maxMembers": 50,
    "maxBoards": 100,
    "maxWorkspaces": 10
  }
}

`GET /api/v1/admin/billing/feature-gate`

Check if the current plan allows a specific gated feature.

tRPC: billing.checkFeatureGate Auth: Bearer token required or session cookie Org context: Required

Parameters:

Name	Type	Required	Description
`feature`	string	Yes	Feature to check: `automations`, `kpis`, `templates`, `csv_import`, `escalation`, `sso`, `api_access`, `custom_branding`, `advanced_analytics`, `audit_log`

SSO Configuration

Per-tenant Single Sign-On configuration supporting OIDC and SAML identity providers. The OIDC client secret is never returned in API responses.

tRPC-Only SSO Procedures

Procedure	Type	Description
`sso.getConfig`	query	Get SSO configuration (admin only, secret masked)
`sso.saveConfig`	mutation	Create or update SSO config (upsert)
`sso.deleteConfig`	mutation	Remove SSO configuration entirely
`sso.testConnection`	mutation	Verify OIDC config by fetching .well-known
`sso.activate`	mutation	Enable SSO after readiness check
`sso.deactivate`	mutation	Disable SSO and turn off enforcement
`sso.toggleEnforcement`	mutation	Enable/disable SSO-only login enforcement

Supported providers: OIDC (any OpenID Connect provider), SAML (with IdP metadata parsing and SP metadata generation)

API Keys

Manage programmatic API keys for REST and MCP access. Keys follow the pattern probeya_sk_live_{40 hex chars} with bcrypt-hashed storage.

Endpoints

`POST /api/v1/admin/api-keys`

Generate a new API key. The full key is returned once in the response and never again.

tRPC: apiKeys.create Auth: Session cookie only (not API key). Role: manage_settings permission required. Org context: Required

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Human-readable label (e.g., “iOS App”, “CI Pipeline”)
`scopes`	string[]	No	Permission scopes to restrict access (empty = full access)
`expiresAt`	string	No	Expiration date (ISO 8601)

Response:

{
  "key": "probeya_sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "apiKey": {
    "id": "clx9ak001",
    "name": "CI Pipeline",
    "prefix": "a1b2c3d4",
    "scopes": ["read:items", "write:items"],
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "createdAt": "2026-04-01T10:00:00.000Z"
  }
}

The full API key is shown only once at creation time. Store it securely — it cannot be retrieved later.

tRPC-Only API Key Procedures

Procedure	Type	Description
`apiKeys.list`	query	List all API keys (hash never returned, prefix shown)
`apiKeys.revoke`	mutation	Permanently revoke a key (irreversible)
`apiKeys.rotate`	mutation	Atomically revoke old key and create new one
`apiKeys.delete`	mutation	Hard-delete a key record

Webhooks

Outgoing webhook management for event-driven integrations. Secrets are auto-generated using 256-bit entropy.

Lifecycle: created → active → disabled (after 10 failures or manual) → re-enabled → deleted

Endpoints

`POST /api/v1/webhooks`

tRPC: webhooks.create Auth: Session cookie. Role: manage_settings permission required. Org context: Required

Parameters:

Name	Type	Required	Description
`url`	string	Yes	HTTPS endpoint URL for POST notifications
`events`	string[]	Yes	Event types to subscribe to (min 1)

tRPC-Only Webhook Procedures

Procedure	Type	Description
`webhooks.list`	query	List all webhooks for the organization
`webhooks.get`	query	Get webhook with delivery log
`webhooks.update`	mutation	Update URL, events, or enabled status
`webhooks.delete`	mutation	Hard-delete a webhook
`webhooks.test`	mutation	Send a synthetic event to verify the endpoint

Integrations (Slack & Teams)

Manage Slack and Microsoft Teams integrations via incoming webhook URLs.

tRPC-Only Integration Procedures

Procedure	Type	Description
`integrations.list`	query	List all messaging integrations
`integrations.create`	mutation	Register Slack or Teams integration with webhook URL
`integrations.update`	mutation	Update name, URL, or subscribed events
`integrations.delete`	mutation	Remove an integration
`integrations.toggle`	mutation	Enable or disable an integration
`integrations.test`	mutation	Send a test message to verify the webhook

Connectors

External system connectors for SAP S/4HANA, MES, QMS, generic REST APIs, and webhook receivers.

Connector lifecycle: pending_setup → active → error | disabled

tRPC-Only Connector Procedures

Procedure	Type	Description
`connectors.create`	mutation	Register a new connector with type, config, sync frequency
`connectors.update`	mutation	Update connector configuration
`connectors.delete`	mutation	Remove a connector
`connectors.list`	query	Paginated list with type and status filters
`connectors.getById`	query	Connector detail with sync history
`connectors.testConnection`	mutation	Verify connectivity using the adapter health check

Site Agents (IoT Gateway)

Industrial edge gateways connecting PLCs, SCADA systems, and IoT devices via OPC-UA, MQTT, S7comm, Modbus, and REST protocols.

Agent lifecycle: offline → online → error | maintenance

tRPC-Only Site Agent Procedures

Procedure	Type	Description
`siteAgents.createAgent`	mutation	Register an edge gateway with protocol and data points
`siteAgents.listAgents`	query	List agents with site, status, protocol filters
`siteAgents.getAgent`	query	Agent detail with recent data points
`siteAgents.updateAgent`	mutation	Update agent config, data points, status
`siteAgents.deleteAgent`	mutation	Remove an agent registration
`siteAgents.ingestDataPoint`	mutation	Push a tag reading from an agent
`siteAgents.listDataPoints`	query	Query time-series data points for an agent

Protocols: opcua, mqtt, s7comm, modbus, rest

Report Schedules

Automated PDF report generation and email delivery on daily, weekly, or monthly cadence.

tRPC-Only Report Schedule Procedures

Procedure	Type	Description
`reportSchedules.list`	query	List all report schedules
`reportSchedules.create`	mutation	Create a schedule with frequency, recipients, and parameters
`reportSchedules.update`	mutation	Update schedule settings
`reportSchedules.delete`	mutation	Delete a schedule
`reportSchedules.toggle`	mutation	Enable or disable a schedule
`reportSchedules.runNow`	mutation	Manually trigger a schedule for testing

Error Codes

Code	Description
400	Invalid input (e.g., unknown feature name, invalid URL)
401	Missing or invalid authentication
403	Insufficient permissions (admin role required for most operations)
404	Entity not found in this organization
409	Conflict (e.g., duplicate SSO configuration)

API Reference

REST API

MCP Server

Admin API

Admin API

Billing

Endpoints

`GET /api/v1/admin/billing/subscription`

`GET /api/v1/admin/billing/feature-gate`

SSO Configuration

tRPC-Only SSO Procedures

API Keys

Endpoints

`POST /api/v1/admin/api-keys`

tRPC-Only API Key Procedures

Webhooks

Endpoints

`POST /api/v1/webhooks`

tRPC-Only Webhook Procedures

Integrations (Slack & Teams)

tRPC-Only Integration Procedures

Connectors

tRPC-Only Connector Procedures

Site Agents (IoT Gateway)

tRPC-Only Site Agent Procedures

Report Schedules

tRPC-Only Report Schedule Procedures

Error Codes

API Reference

REST API

MCP Server

​Admin API

​Billing

​Endpoints

​GET /api/v1/admin/billing/subscription

​GET /api/v1/admin/billing/feature-gate

​SSO Configuration

​tRPC-Only SSO Procedures

​API Keys

​Endpoints

​POST /api/v1/admin/api-keys

​tRPC-Only API Key Procedures

​Webhooks

​Endpoints

​POST /api/v1/webhooks

​tRPC-Only Webhook Procedures

​Integrations (Slack & Teams)

​tRPC-Only Integration Procedures

​Connectors

​tRPC-Only Connector Procedures

​Site Agents (IoT Gateway)

​tRPC-Only Site Agent Procedures

​Report Schedules

​tRPC-Only Report Schedule Procedures

​Error Codes

Admin API

Billing

Endpoints

`GET /api/v1/admin/billing/subscription`

`GET /api/v1/admin/billing/feature-gate`

SSO Configuration

tRPC-Only SSO Procedures

API Keys

Endpoints

`POST /api/v1/admin/api-keys`

tRPC-Only API Key Procedures

Webhooks

Endpoints

`POST /api/v1/webhooks`

tRPC-Only Webhook Procedures

Integrations (Slack & Teams)

tRPC-Only Integration Procedures

Connectors

tRPC-Only Connector Procedures

Site Agents (IoT Gateway)

tRPC-Only Site Agent Procedures

Report Schedules

tRPC-Only Report Schedule Procedures

Error Codes