Auth Gateway
Reference for the Imperal Auth Gateway public API (auth.imperal.io) — identity, JWT auth, extensions, marketplace, billing, developer portal, secrets, tenants, and real-time events.
The Imperal Auth Gateway (auth.imperal.io) is the public API host for the Imperal Cloud platform. Every user-facing request crosses it. It issues JWTs, applies RBAC, records all actions in the audit ledger, and exposes the full developer-facing REST surface.
Specs
| Link | |
|---|---|
| Live spec (always current) | https://auth.imperal.io/v1/openapi.json |
| Downloadable snapshot | /openapi/auth-gateway.json |
The live spec is the filtered public endpoint — internal/service routes are excluded. It is CORS-open and can be imported directly into any OpenAPI-compatible tool.
Base URL
https://auth.imperal.ioAuthentication
All endpoints (except /v1/auth/signup, /v1/auth/login, /v1/auth/refresh, and /v1/auth/.well-known/jwks.json) require one of:
Authorization: Bearer <jwt>— issued byPOST /v1/auth/loginX-Service-Token: <token>— for trusted backend callers (kernel/service-only routes)
See the API Reference index for the full auth flow.
Public endpoint groups
Auth
Identity and session management.
| Method | Path | Description |
|---|---|---|
POST | /v1/auth/signup | Self-service user registration (email + verify-email flow) |
POST | /v1/auth/verify-email | Complete registration with emailed token |
POST | /v1/auth/login | Obtain JWT from credentials |
POST | /v1/auth/refresh | Rotate JWT using refresh token |
POST | /v1/auth/logout | Invalidate session |
GET | /v1/auth/me | Current user profile |
POST | /v1/auth/me/change-password | Change password |
GET | /v1/auth/.well-known/jwks.json | Public JWK set for token verification |
POST /v1/auth/register is a service-token-gated programmatic registration route — it is not for user-facing clients. Use POST /v1/auth/signup for public user self-registration.
API Keys
Long-lived API keys for non-interactive integrations.
| Method | Path | Description |
|---|---|---|
POST | /v1/keys | Create an API key |
GET | /v1/keys | List API keys |
DELETE | /v1/keys/{key_id} | Revoke a key |
Tenants
Multi-organisation scope. Direct users have tenant_id == imperal_id.
| Method | Path | Description |
|---|---|---|
POST | /v1/tenants | Create a tenant |
GET | /v1/tenants | List tenants |
GET | /v1/tenants/{tenant_id} | Get tenant details |
PATCH | /v1/tenants/{tenant_id} | Update tenant |
DELETE | /v1/tenants/{tenant_id} | Delete tenant |
GET | /v1/tenants/{tenant_id}/health | Tenant health check |
Billing
User-facing wallet, plans, and payment management.
| Method | Path | Description |
|---|---|---|
GET | /v1/billing/plans | List available plans |
GET | /v1/billing/balance | Current credit balance |
GET | /v1/billing/usage | Quota and consumption |
GET | /v1/billing/wallet | Wallet details |
GET | /v1/billing/wallet/history | Transaction history |
POST | /v1/billing/subscribe | Subscribe to a plan |
POST | /v1/billing/topup | Top up wallet |
POST | /v1/billing/checkout | Initiate checkout session |
POST | /v1/billing/payment-methods/setup | Add a payment method |
GET | /v1/billing/payment-methods | List payment methods |
DELETE | /v1/billing/payment-methods/{pm_id} | Remove a payment method |
Extensions — call surface
| Method | Path | Description |
|---|---|---|
POST | /v1/extensions/{app_id}/call | Invoke a @chat.function on an extension |
POST | /v1/extensions/{app_id}/batch | Invoke multiple functions in one round-trip |
See Endpoint 5 in the API map for the full request/response shape and the deploy_ir example.
Extensions — user registry
| Method | Path | Description |
|---|---|---|
GET | /v1/me/extensions | List installed extensions with function manifests |
POST | /v1/me/extensions/disable | Disable an extension |
DELETE | /v1/me/extensions/disable/{app_id} | Re-enable an extension |
GET | /v1/extensions/{app_id}/users | Users with access to an extension |
Marketplace
| Method | Path | Description |
|---|---|---|
GET | /v1/marketplace/apps | Browse published extensions |
GET | /v1/marketplace/apps/{app_id} | Extension details |
GET | /v1/marketplace/featured | Featured extensions |
GET | /v1/marketplace/categories | Available categories |
POST | /v1/marketplace/apps/{app_id}/install | Install an extension |
DELETE | /v1/marketplace/apps/{app_id}/install | Uninstall an extension |
POST | /v1/marketplace/apps/{app_id}/reviews | Submit a review |
GET | /v1/marketplace/apps/{app_id}/reviews | List reviews |
Developer Portal
| Method | Path | Description |
|---|---|---|
POST | /v1/developer/register | Enroll as a developer |
GET | /v1/developer/profile | Developer profile |
POST | /v1/developer/apps | Create an app record |
GET | /v1/developer/apps | List your apps |
GET | /v1/developer/apps/{app_id} | App details |
PUT | /v1/developer/apps/{app_id} | Update app metadata |
DELETE | /v1/developer/apps/{app_id} | Delete app |
POST | /v1/developer/apps/{app_id}/deploys | Record a deploy |
GET | /v1/developer/apps/{app_id}/deploys | Deploy history |
POST | /v1/developer/apps/{app_id}/submit | Submit for review |
GET | /v1/developer/earnings | Earnings overview |
POST | /v1/developer/payouts/request | Request a payout |
Secrets
Per-extension secret management. Accessed through ctx.secrets in extension handlers.
| Method | Path | Description |
|---|---|---|
GET | /v1/secrets/{ext_id} | List secret metadata for an extension |
PUT | /v1/secrets/{ext_id}/{name} | Set a secret value |
DELETE | /v1/secrets/{ext_id}/{name} | Delete a secret |
POST | /v1/secrets/{ext_id}/{name}/rotate | Rotate a secret |
Automations
POST /v1/automations is deprecated. Automation management is handled through the automations extension via POST /v1/extensions/automations/call.
| Method | Path | Description |
|---|---|---|
GET | /v1/automations | List automations |
DELETE | /v1/automations/{rule_id} | Delete an automation |
POST | /v1/automations/{rule_id}/pause | Pause an automation |
POST | /v1/automations/{rule_id}/resume | Resume an automation |
Actions & audit
Read-only view of the action ledger for the authenticated user.
| Method | Path | Description |
|---|---|---|
GET | /v1/actions | List actions |
GET | /v1/actions/{trace_id} | Action details |
GET | /v1/actions/stats | Action statistics |
GET | /v1/actions/stats/extension/{app_id} | Stats per extension |
Confirmations & Tasks
| Method | Path | Description |
|---|---|---|
GET | /v1/confirmations/active | Active confirmation cards |
POST | /v1/confirmations/{id}/confirm | Confirm an action |
POST | /v1/confirmations/{id}/cancel | Cancel a pending action |
GET | /v1/tasks/active | Active background tasks |
DELETE | /v1/tasks/{task_id} | Cancel a task |
Events
| Method | Path | Description |
|---|---|---|
GET | /v1/events/stream | SSE stream of real-time kernel events |
Webhooks
| Method | Path | Description |
|---|---|---|
GET | /v1/ext/{app_id}/webhook/{path} | Extension webhook (OAuth callbacks, push) |
POST | /v1/webhooks/stripe | Stripe payment event callback |
Developer API Map
Curated quickstart for the Imperal Cloud public API — services overview, the 15 key endpoints with curl examples, and gotchas every developer should know.
Registry
Reference for the Imperal Cloud Registry API — extension discovery, tool manifests, app settings, and catalog metadata used by the web-kernel at session start.