Skip to main content

Authentication and base URLs

Noonum runs a single production environment. Point REST API integrations at https://api.noonum.ai/v2 and MCP clients at https://mcp.noonum.ai/mcp. Both authenticate with a Bearer token. The full setup (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 hello@noonum.com.
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.
  • 423 Locked from POST /strategies/{strategyId}/submit: a run for this version and date is already in progress. Wait for it to finish before you submit again.
  • 429 Too Many Requests from POST /strategies/{strategyId}/submit: your plan doesn’t have enough credits left in the current period. Each run, live or historical, uses one credit. A failed run is not charged. Don’t retry, since the request keeps failing until your credits refill. The response body reports the credits you have left (available) and the credits the submission needed (requested). GET /usage returns when your credits refill (refills_at). To get more credits, contact support.
  • Other 4xx codes, such as 400 and 404: a problem with the request itself. Fix it; don’t retry unchanged.
  • 5xx: a transient server-side error. 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.

Credits and retries

Your plan’s credits limit how many strategy runs you can start in each period. Design clients to retry transient failures and to stop on errors that a retry can’t fix.
  • Retry on 5xx only. A 4xx won’t succeed on an immediate retry, so handle it as described in Error handling.
  • 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 503 response includes a Retry-After header, wait at least that long before retrying.
  • Cap retries (for example 4 to 5 attempts), then fail rather than hammering the REST API indefinitely.
  • Smooth your own request rate. Add client-side concurrency limits and spread bulk work over time.

Pre-launch checklist

Before pointing production traffic at Noonum:
  • All requests target https://api.noonum.ai/v2 (REST API) or https://mcp.noonum.ai/mcp (MCP server).
  • Every request that uses an API key sends it 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.
  • 429 handling stops submitting runs and reports that your plan’s credits ran out.
  • Retry logic covers 5xx only, 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.