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.
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. | |
| Audit | Query and export audit logs. |
| Directory sync | Configure sync behavior and read sync events. |
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 \
-H "Authorization: Bearer $SWITERA_SECRET_KEY"
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. |