API

Security And Best Practices

Store keys safely, rotate credentials, redact logs, retry carefully, cache responsibly, and protect downstream data.

Protect API keys, downstream data, logs, retries, and production integrations.

Treat API keys as production secrets.

An API key can access authorized Kommon Poll data for the team selected when the key was created.

1. Key Storage

Store keys in:

  • A secrets manager.
  • Server environment variables.
  • Approved deployment secrets.
  • Secure CI or job-runner secret storage.

Do not store keys in:

  • Source code.
  • Git history.
  • Browser JavaScript.
  • Mobile apps.
  • Shared screenshots.
  • Client-side config files.
  • URLs or query strings.

2. Key Scope And Rotation

Use one key per integration and environment.

Examples:

  • Power BI Production
  • Power BI Staging
  • Weekly Report Job
  • Data Warehouse Import

Rotate keys periodically according to your organization's secret-management policy.

Revoke keys immediately when they are exposed, unused, or no longer needed.

3. Server-Side Use

Call the API from trusted server-side code.

Avoid direct browser-to-API calls because bearer keys can be exposed to users.

If a frontend needs Kommon Poll data, use your own backend to:

  • Authenticate the user.
  • Call the Kommon Poll API securely.
  • Return only the data needed by the frontend.
  • Apply your organization's access rules.

4. Logging Hygiene

Logs should capture:

  • Status code.
  • Endpoint.
  • Request duration.
  • Job or integration name.
  • Non-secret request parameters.
  • Request ID if returned.

Logs should redact:

  • Authorization header.
  • API key values.
  • Raw error messages that contain secrets.
  • Exported datasets unless the log location is approved for that data.

5. Retries And Timeouts

Use explicit request timeouts.

Retry only:

  • 429
  • 500
  • 502
  • 503

Use bounded exponential backoff with jitter.

Do not retry 400, 401, 403, or 404 responses without changing the request, credentials, access, or aid.

6. Caching And Exports

Cache responsibly:

  • Cache GET /v4/list for configuration screens where appropriate.
  • Cache overview responses briefly when dashboards refresh frequently.
  • Avoid repeated full-page exports when only new mention pages are needed.
  • Checkpoint large exports by dataFrom, page size, date range, and job run.

Use pagination for large datasets.

Keep downstream data only as long as required for the integration's business purpose.

7. Sharing Output

When sharing reports externally:

  • State the reporting period.
  • State the filters used.
  • Preserve appropriate source attribution.
  • Respect source and platform restrictions.
  • Avoid implying reach is unique people unless that is explicitly measured.
  • Separate measured metrics from interpretation and recommendations.