API reference
Switera exposes app and service APIs under the Switera API base path. This page gives Builders the public-safe map of the API families and integration rules.
The full machine-readable API schema should be published only after it is sanitized for public consumption. Do not publish generated schemas that expose internal package names, private implementation details, or backend service names.
The repository-generated reference has been refreshed from the current backend route annotations. Use SDK and API coverage to choose an SDK, and use docs/api-docs in the source tree when you need the exact generated route list while the public reference is being curated.
Main API families
| Family | Use it for |
|---|---|
| Apps | Create, list, update, and delete apps. |
| Tenants and organizations | Manage organizations, members, domains, groups, and invitations. |
| Auth settings | Configure app-level Auth policy and providers. |
| Users | Search, update, secure, and inspect end users. |
| API keys | List and rotate app credentials. |
| OAuth2 | Read client info and manage redirect URIs. |
| Webhooks | Manage endpoints, event catalog, deliveries, attempts, and replay. |
| Configure sender routes, templates, managed email, runtime, and suppressions. | |
| Billing | Manage billing customer mappings, plans, subscriptions, usage overview, and invoice visibility. |
| Audit | Query and export audit logs. |
| Directory sync | Configure sync behavior and read sync events. |
| FGA | Write authorization models, tuple changes, permission checks, object lists, and subject lists. |
| Vault | Manage app-scoped keys, encryption, decryption, signing, verification, tokenization, detokenization, and encrypted objects. |
| Storage and managed data | Manage object storage, object quotas, app data collections, records, usage, and quota settings. |
| Search | Query and reindex user search documents. |
| Radar and actions | Read risk signals, configure app risk policy, and inspect action/event surfaces. |
| Widgets | Read widget config and call widget login/registration routes. |
Base URL
Use the public Switera API base:
https://switera.com/api
Most app-scoped API routes follow this shape:
/v1/apps/{appId}/...
Authentication
Use the authentication method required by the endpoint. For server-to-server calls, use an app-scoped secret key from a trusted backend.
Example:
curl "https://switera.com/api/v1/apps/$APP_ID/billing/overview" \
-H "Authorization: Bearer $SWITERA_SECRET_KEY"
See API management and limits for app-scoped key controls and Usage, invoices, and API for Billing route examples.
See SDK and API coverage for package names, runtime targets, and which product APIs have typed SDK helpers.
Request design
- Send JSON with
Content-Type: application/jsonwhen the endpoint expects JSON. - Use pagination parameters where list endpoints support them.
- Treat IDs as opaque strings.
- Store secret values securely.
- Do not retry mutating requests without understanding idempotency.
Error handling
API errors can include an error code, message, and details. Log the code and request context in your backend, but do not log secret keys or sensitive payloads.
Common responses:
| Status | Meaning |
|---|---|
| 400 | Request body or parameter is invalid. |
| 401 | Missing or invalid authentication. |
| 403 | Authenticated caller is not allowed to perform the action. |
| 404 | Resource does not exist or is not visible to the caller. |
| 409 | Resource conflict, such as a duplicate slug. |
| 500 | Server error. Retry only when the operation is safe. |
Generated reference status
The generated Markdown reference in docs/api-docs is rebuilt from src/api/docs/swagger.json with:
scripts/refresh-api-docs.sh
It currently tracks 212 API paths across the launch backend surface. Before making it the primary public reference, Switera still needs to curate operation IDs, examples, and generated model naming for external readers.