Skip to main content

​
Authentication and base URLs

Noonum runs a single production environment. Point every integration, REST or MCP, at the one base URL and authenticate with a Bearer token. The full setup (base URLs, the Authorization header, and how to request a key) is on the Authentication page. The Noonum API key is a static, long-lived credential that requires no round-trip, which suits server-side jobs, cron, ETL, and other services that run without a human present. Interactive MCP clients that sign users in are set up differently. See MCP client setup.

​
Key hygiene

Treat an API key like a password. It grants full access to your account.
  • Never embed API keys in client-side code. Browser bundles, mobile apps, and anything shipped to a user device are inspectable. A key placed there is effectively public. Keep keys server-side only.
  • Inject secrets at runtime, from environment variables or a secrets manager. Do not commit keys to source control, logs, screenshots, or support tickets.
  • Use separate keys per environment or service where possible, so one can be revoked without disrupting the others.
  • Rotate keys on a schedule and immediately if one may have leaked. To rotate or revoke a key, contact support at [email protected].
If a key is exposed (committed, logged, or shared), assume it is compromised and request a rotation from support right away.

​
Error handling

Build your integration to react to HTTP status codes, not just the response body. The full status-code reference lives in the REST integration tutorial. For production, these are the behaviors that matter:
  • 401 Unauthorized: the request wasn’t authenticated, from a missing or malformed Authorization header, an invalid/revoked/rotated key, or an inactive account. Surface the failure and check the key. Don’t retry, since the same bad credential will keep failing. If the key was rotated, update your secret store.
  • 4xx (e.g. 400, 404): a problem with the request itself. Fix it; don’t retry unchanged.
  • 429 and 5xx: transient (rate limiting or a server-side blip). Retry with backoff, as below.
Always read the response body for a machine-readable error and log it (with secrets redacted) so failures are diagnosable in production.

​
Rate limits and retries

Noonum applies rate limiting to protect the service. Design clients to expect throttling and to retry transient failures.
  • Retry on 429 and 5xx. Do not retry on 4xx other than 429, since those won’t succeed without a change to the request.
  • Use exponential backoff with jitter. Increase the wait between attempts (for example 1s, 2s, 4s, 8s) and add a small random offset so concurrent clients don’t retry in lockstep.
  • Honor Retry-After when present. If a 429 or 503 response includes a Retry-After header, wait at least that long before retrying.
  • Cap retries (for example 4–5 attempts), then fail rather than hammering the API indefinitely.
  • Smooth your own request rate. Add client-side concurrency limits and spread bulk work over time.
attempt 1 → fail (429) → wait ~1s  + jitter
attempt 2 → fail (429) → wait ~2s  + jitter
attempt 3 → fail (5xx) → wait ~4s  + jitter
attempt 4 → success

​
Pre-launch checklist

Before pointing production traffic at Noonum:
  • All requests target https://api.noonum.ai/v2 (REST) or https://api.noonum.ai/v1/mcp (MCP).
  • Every request sends the API key as Authorization: Bearer <api-key>.
  • No API key is present in any client-side bundle, mobile app, or repository.
  • Keys are loaded from environment variables or a secrets manager at runtime.
  • A key rotation path is documented and known to the team.
  • 401 handling surfaces the failure and checks the credential.
  • Retry logic uses exponential backoff with jitter, honors Retry-After, and is capped.
  • Errors and status codes are logged (with secrets redacted) for production diagnosis.
  • Timeouts and concurrency limits are set so a slow dependency can’t stall your app.