Substratal Apps Substratal Apps Hub specs
GitHub

Help API reference v1

Endpoints · Substratal-Version: 1

All 128 operations in openapi.yaml 1.0.0-draft.13, grouped by area, with the Hub screens that use each one. destructive marks operations an agent key with restrict_destructive can't call.

Meta

MethodPathSummaryAuthScreens
GET/health no version header neededHealth checkNoneGLB-03

Auth

MethodPathSummaryAuthScreens
POST/auth/signupCreate an account with email and passwordNoneAUTH-03
POST/auth/loginExchange email and password for a session (or an MFA challenge)NoneAUTH-01
POST/auth/mfa/verifyComplete a login that returned an MFA challengeNoneAUTH-02
POST/auth/token/refreshRotate a platform refresh token for a new access tokenNoneGLB-03
POST/auth/logout destructiveRevoke the current session, or every sessionBearerACC-01 GLB-03
POST/auth/app-tokensMint a per-app JWT from a platform session (embedded login)BearerAPP-03
POST/auth/oauth/authorization-codesMint a one-time authorization code for a hosted launch (PKCE)BearerAPP-03
POST/auth/oauth/token no version header neededExchange an authorization code or app refresh token for an app tokenNone
POST/auth/email/verifyConfirm an email address from an emailed tokenNoneAUTH-04
POST/auth/email/verify/resendRe-send a verification email (always 202)NoneAUTH-04
POST/auth/password/forgotSend a password-reset email (always 202)NoneAUTH-05
POST/auth/password/resetSet a new password from a reset token (revokes every session)NoneAUTH-06
POST/auth/invitations/acceptSet a password on an invited account, activate it, and sign inNoneAUTH-07
POST/auth/sso/{provider}/callbackComplete an SSO login (reserved — 501 until the broker integration ships)NoneAUTH-01
POST/users/{id}/passwordChange password given the current one (self only)BearerACC-03
POST/users/{id}/mfa/totpBegin TOTP enrollment (self only)BearerACC-05
DELETE/users/{id}/mfa/totp destructiveSupport reset of a user's TOTP (requires users.manage)BearerUSR-03
POST/users/{id}/mfa/totp/confirmConfirm TOTP enrollment with a first code; returns recovery codes onceBearerACC-05
POST/users/{id}/mfa/totp/disableTurn TOTP off given a current code or recovery code (self only)BearerACC-06
GET/users/{id}/sessionsList active sessions (self or users.manage)BearerACC-04 USR-04
POST/users/{id}/sessions/revoke-all destructiveRevoke every session (self or users.manage)BearerACC-04 USR-04
DELETE/users/{id}/sessions/{sessionId} destructiveRevoke one sessionBearerACC-04 USR-04

Users

MethodPathSummaryAuthScreens
GET/usersList or search usersBearerUSR-01 NTF-06 GLB-01 ROL-02
POST/usersCreate (invite) a userBearerUSR-02
GET/users/{id}Fetch one userBearerACC-01 ACC-04 APP-01 USR-03
PATCH/users/{id} destructiveUpdate email (self, pending verification) or status (users.manage)BearerACC-02 USR-03
DELETE/users/{id} destructiveSoft-delete a user (self or users.manage)BearerUSR-03
POST/users/{id}/suspend destructiveSuspend a user (users.manage)BearerUSR-05
POST/users/{id}/invitationRe-send the invitation email to an invited user (users.manage)BearerUSR-03
GET/users/{id}/exportExport everything this API holds about this userBearerACC-07 USR-03
POST/users/{id}/erasure-requests destructiveRequest right-to-erasure (soft-delete now, hard-delete cascade in 7 days)BearerACC-08
DELETE/users/{id}/erasure-requests/current destructiveCancel a scheduled erasure inside its 7-day window (users.manage)BearerUSR-03

Profiles

MethodPathSummaryAuthScreens
GET/users/{id}/profileFetch global ProfileBearerACC-01 USR-03
PATCH/users/{id}/profileUpdate global Profile (self or users.manage)BearerACC-01
GET/users/{id}/apps/{appId}/profileFetch per-app AppProfile (self, the app's own key, or platform users.list; defaults if none written yet)BearerAPP-04
PATCH/users/{id}/apps/{appId}/profileUpdate per-app AppProfile (custom is merged one level; null removes a key)BearerAPP-04

Settings

MethodPathSummaryAuthScreens
GET/users/{id}/settingsFetch global Settings (self, or platform users.list)BearerSET-01 NTF-03
PATCH/users/{id}/settingsUpdate global Settings (self or users.manage)BearerSET-01
GET/users/{id}/apps/{appId}/settingsFetch fully resolved per-app settings (self, the app's own key, or platform users.list)BearerSET-02 SET-01
PATCH/users/{id}/apps/{appId}/settingsWrite per-app overrides (validated against settings_schema; null clears)BearerSET-02 SET-01

Applications

MethodPathSummaryAuthScreens
GET/applicationsList the catalog (filtered by visibility rules)BearerAPP-01 ACX-01 APL-01 BIL-01 NTF-01
POST/applicationsRegister an Application (applications.manage, or self-service into review)BearerAPL-02
GET/applications/{id}Fetch one ApplicationBearerAPP-02 SET-02 APL-03
PATCH/applications/{id} destructiveUpdate a catalog entry (owner — configuration; applications.manage — anything)BearerAPL-03 APL-04 APL-05 APL-06
DELETE/applications/{id} destructiveDelete an unreferenced test-mode Application (applications.manage)Bearer

Entitlements

MethodPathSummaryAuthScreens
GET/users/{id}/entitlementsA user's entitlements, personal and org-sourcedBearerAPP-01 APP-05 ACX-01
POST/users/{id}/entitlementsGrant a personal EntitlementBearerACX-02
GET/entitlementsList entitlements across users (entitlements.manage or the Application's owner; app keys and owners confined)BearerACX-05
GET/entitlements/{id}Fetch one entitlementBearerACX-03
PATCH/entitlements/{id} destructiveThe toggle: change status, term, source (trial→purchase), order_id, or an org grant's member scopeBearerORG-06 ORG-07 ACX-01 ACX-03
DELETE/entitlements/{id} destructiveHard-remove a grant made in error (no order_id, under 24 hours old)BearerACX-01

Roles & Permissions

MethodPathSummaryAuthScreens
GET/permissionsList every Permission key the caller can seeBearerROL-01 ROL-02
GET/rolesList RolesBearerROL-01
POST/rolesDefine a RoleBearerROL-03
GET/roles/{id}Fetch one RoleBearerROL-02
PATCH/roles/{id} destructiveChange a Role's permissions or descriptionBearerROL-02
DELETE/roles/{id} destructiveDelete an unassigned, non-seed RoleBearerROL-02
GET/users/{id}/rolesList a user's Role assignments (including implicit default_app_role)BearerROL-04
POST/users/{id}/roles/{roleId}Assign a Role (idempotent — 200 if already held)BearerROL-04
DELETE/users/{id}/roles/{roleId} destructiveRemove a Role assignment (idempotent)BearerROL-04
GET/users/{id}/apps/{appId}/effective-permissionsThe live access check (always 200)BearerAPP-02 ACX-04

Organizations

MethodPathSummaryAuthScreens
GET/organizationsList your Organizations (all, with organizations.manage)BearerAPP-01 ORG-01
POST/organizationsCreate an Organization (any active User; caller becomes org_admin)BearerORG-02
GET/organizations/{id}Fetch one OrganizationBearerORG-03
PATCH/organizations/{id} destructiveRename (org admin), or suspend/reactivate (organizations.manage)BearerORG-08
GET/organizations/{id}/membersList membersBearerORG-03 BIL-02
POST/organizations/{id}/membersInvite a member by email (org admin), or add one directly by user_id (organizations.manage)BearerORG-04
POST/organizations/{id}/members/me/acceptAccept a pending membership (the invited User's own token)BearerORG-09
PATCH/organizations/{id}/members/{userId} destructiveChange a member's roleBearerORG-05
DELETE/organizations/{id}/members/{userId} destructiveRemove a member or withdraw an invitation; or leave or decline (userId = me)BearerORG-05 ORG-08 ORG-09
GET/organizations/{id}/scim-tokenShow the Organization's SCIM token (never its secret)BearerORG-08
POST/organizations/{id}/scim-tokenCreate (or rotate) the Organization's SCIM tokenBearerORG-08
DELETE/organizations/{id}/scim-tokenTurn SCIM off for the OrganizationBearerORG-08
GET/organizations/{id}/entitlementsList org-wide (seat) grantsBearerORG-06
POST/organizations/{id}/entitlementsGrant an app to the whole OrganizationBearerORG-07

Tenancy

MethodPathSummaryAuthScreens
GET/tenantsList Tenants (your own; all with tenants.manage)BearerBIL-04
GET/tenants/{id}Fetch one TenantBearerBIL-04
GET/tenants/{id}/tier-change-requestsList tier-change requests for a TenantBearerBIL-04
POST/tenants/{id}/tier-change-requests destructiveOpen a tier-change request on a customer's behalf (tenants.manage)BearerBIL-04
GET/tenants/{id}/tier-change-requests/{requestId}Fetch one tier-change requestBearerBIL-04
PATCH/tenants/{id}/tier-change-requests/{requestId} destructiveSchedule, start, complete, or cancel a tier-change request (tenants.manage)BearerBIL-04

Billing

MethodPathSummaryAuthScreens
GET/subscriptionsList every subscriber's subscription (billing.manage)BearerRPT-01
GET/users/{id}/subscriptionA User's plan, what covers it, and their own subscription (self or billing.manage)BearerUSR-03 BIL-01
POST/users/me/billing/checkout-sessionsStart a Stripe Checkout to subscribe yourself to Standard (User token)BearerBIL-03
POST/users/me/billing/portal-sessionsOpen the Stripe Customer Portal for your own subscription (User token)BearerBIL-03
GET/organizations/{id}/subscriptionAn Organization's plan and Standard subscription (org admin or billing.manage)BearerBIL-02
PATCH/organizations/{id}/subscriptionChoose which members the Organization's subscription covers (org admin)BearerBIL-02
POST/organizations/{id}/billing/checkout-sessionsStart a Stripe Checkout to subscribe the Organization to Standard (org admin, User token)BearerBIL-03
POST/organizations/{id}/billing/portal-sessionsOpen the Stripe Customer Portal for the Organization's subscription (org admin or billing.manage, User token)BearerBIL-03

Audit

MethodPathSummaryAuthScreens
GET/audit-eventsQuery the audit log (hot window only)BearerKEY-04 AUD-01
GET/audit-events/{id}Fetch one Audit EventBearerAUD-02
POST/audit-exportsExport Audit Events to a file (asynchronous)BearerAUD-01
GET/audit-exports/{id}Fetch an export's status, and its download link once readyBearerAUD-01

Webhooks

MethodPathSummaryAuthScreens
GET/webhooksList subscriptions visible to the callerBearerWHK-01
POST/webhooksSubscribe a URL to event typesBearerWHK-02
GET/webhooks/{id}Fetch one subscriptionBearerWHK-03
PATCH/webhooks/{id}Change url, events, description, api_version, or re-enableBearerWHK-02
DELETE/webhooks/{id} destructiveUnsubscribeBearerWHK-03
POST/webhooks/{id}/rotate-secretIssue a new signing secret (24-hour overlap)BearerWHK-03
POST/webhooks/{id}/testSend a webhook.test event nowBearerWHK-03
GET/webhooks/{id}/deliveriesRecent delivery attempts (30-day log)BearerWHK-03
GET/webhook-deliveriesDelivery attempts across every subscription visible to the caller (30-day log)Bearer
POST/webhooks/{id}/deliveries/{deliveryId}/redeliverRe-send one past event (same event id)BearerWHK-03

Notifications

MethodPathSummaryAuthScreens
GET/push-credentialsList push credentials across every Application (applications.manage)Bearer
GET/applications/{id}/push-credentialsList the push providers an Application has configured (the owner, the app's own key, or applications.manage)BearerAPL-07
POST/applications/{id}/push-credentialsConfigure one push provider (the owner or applications.manage, User token only)BearerAPL-07
GET/applications/{id}/push-credentials/{provider}Fetch one provider's configurationBearerAPL-07
PATCH/applications/{id}/push-credentials/{provider}Replace key material, change non-secret fields, or re-enable a failed credential (User token only)BearerAPL-07
DELETE/applications/{id}/push-credentials/{provider} destructiveRemove a push provider (User token only)BearerAPL-07
GET/users/{id}/devicesList a User's push devices (self, the app's own key, or users.list)BearerNTF-03 NTF-05
POST/users/{id}/devicesRegister a push device, or refresh an existing registration (self or the app's own key)BearerNTF-04
GET/users/{id}/devices/{deviceId}Fetch one deviceBearerNTF-05
PATCH/users/{id}/devices/{deviceId}Update a device's name, app version, environment, or rotated token (self or the app's own key)BearerNTF-03 NTF-04
DELETE/users/{id}/devices/{deviceId} destructiveUnregister a device (self, the app's own key, or users.manage)BearerNTF-03 NTF-05
POST/users/{id}/devices/{deviceId}/testSend a test push to one device and wait for the provider's answer (self or the app's own key)BearerNTF-03
GET/users/{id}/notificationsList a User's notification inbox (self, the app's own key, or users.list)BearerNTF-01 NTF-05
POST/users/{id}/notificationsSend one notification to one User (the app's own key with notifications.send, or platform notifications.send)BearerNTF-06
GET/users/{id}/notifications/unread-countCount unread notifications, in total and per Application (self or the app's own key)BearerAPP-01 NTF-01 GLB-03
POST/users/{id}/notifications/mark-readMark every unread notification matching the filters as read (self or the app's own key)BearerNTF-01
GET/users/{id}/notifications/{notificationId}Fetch one notification, with its per-device deliveriesBearerNTF-02 NTF-05
PATCH/users/{id}/notifications/{notificationId}Mark one notification read, unread, or archived (self or the app's own key)BearerNTF-01 NTF-02

API Keys

MethodPathSummaryAuthScreens
GET/api-keysList keys the caller may manageBearerKEY-01
POST/api-keysCreate a key (api_keys.manage, or the Application's owner for an app-scoped key)BearerKEY-02
GET/api-keys/{id}Fetch one key (never the secret)BearerKEY-04
PATCH/api-keys/{id} destructiveChange name, permissions, or restrict_destructiveBearerKEY-04
DELETE/api-keys/{id} destructiveRevoke permanentlyBearerKEY-04
POST/api-keys/{id}/rotate destructiveIssue a new secret, invalidating the old one immediately (no overlap)BearerKEY-04

Last updated 2026-10-23 · Built 2026-10-25 from a9ef3be · API 1.0.0-draft.13 · Substratal-Version: 1