API management and limits

Use API management when your backend needs to call Switera on behalf of one app. Secret keys are app-scoped credentials for trusted servers. They can be limited by scope, expiration, caller IP, per-key request rate, and organization request rate.

Server-to-server model​

Backend calls use the app ID in the URL and a secret key in the Authorization header:

curl "https://switera.com/api/v1/apps/$APP_ID/tenants" \
  -H "Authorization: Bearer $SWITERA_SECRET_KEY"

Keep these rules strict:

• Use secret keys only from trusted backend services.
• Do not put secret keys in browsers, mobile apps, public logs, screenshots, tickets, or frontend bundles.
• Use publishable keys only where the API expects a public app identifier.
• Keep test and live keys separate.
• Rotate a key before removing the old value from a running backend.

Public route classes​

Switera exposes one public domain for the builder console, hosted app flows, documentation, and API traffic. The path determines which auth model applies.

For API-key calls, the path app ID is part of the authorization boundary. A secret key for one app cannot read or mutate another app by changing the {appId} in the URL.

Key controls​

Open Admin > API Keys inside an app to edit secret-key controls.

Available scopes:

Request usage​

The API Keys page shows a 30-day rollup for each secret key:

• total requests
• successes
• errors
• rate-limited requests
• average latency
• last-used timestamp

The same data is available from your backend:

curl "https://switera.com/api/v1/apps/$APP_ID/keys/usage?days=30" \
  -H "Authorization: Bearer $SWITERA_SECRET_KEY"

Usage is aggregated by app and key. Tenant slot data is captured internally for future organization breakdowns, but the launch UI shows per-key totals.

Organization API limits​

Organization API limits protect one customer organization from consuming unlimited app management traffic through tenant-scoped routes. The setting applies to secret app API-key requests under:

/api/v1/apps/{appId}/tenants/{tenantId}/...

To update the same setting from your backend:

curl -X PUT "https://switera.com/api/v1/apps/$APP_ID/tenants/$ORG_ID/settings" \
  -H "Authorization: Bearer $SWITERA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_rate_limit_per_minute": 120
  }'

When a key or organization exceeds a request limit, Switera returns 429 and rate-limit headers:

App-scoped route map​

These are the main app management route groups available to trusted backends. The table uses organization in descriptions, while the API path keeps the launch contract name tenants.

Isolation and status-code contract​

Use these responses when testing an integration:

Only authenticated app-scoped secret-key traffic is counted in API request usage and usage-based Billing meters. Browser-session calls and rejected wrong-app keys are not treated as successful app API usage.

Troubleshooting​

Related pages:

• API keys
• Developer integration checklist
• Create and manage organizations
• Troubleshooting