Analytics API Authentication

The Coldtivate analytics API uses long-lived API tokens for partner dashboards and integrations. These tokens are separate from the app's normal sign-in sessions and JWT access tokens. Use them only for server-to-server requests from trusted partner systems.

Base URL

Production:

https://api.coldtivate.org/api/v1

Staging and partner-specific base URLs are provided during onboarding.

Token Generation

API tokens are generated by a Registered Employee for the company whose analytics data will be accessed. Token management is available through the management API. A token is shown only once when it is created. Store it securely in your integration's secret manager.

When creating a token, choose:

A descriptive name, such as KoldHubs dashboard production.
The minimum scopes required by the integration.
An expiry date, unless the token explicitly needs to be non-expiring.

Management API shape:

curl -X POST "https://api.coldtivate.org/api/v1/api-tokens" \
  -H "Authorization: Bearer <registered-employee-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "KoldHubs dashboard production",
    "scopes": ["users", "utilization", "impact", "sensor_data"],
    "cooling_unit_ids": [],
    "expires_at": "2027-06-08T00:00:00Z"
  }'

Response shape:

{
  "id": "8f1b5d5c-6b61-48f4-a1d8-42f8f8448c38",
  "name": "KoldHubs dashboard production",
  "company_id": 42,
  "scopes": ["users", "utilization", "impact", "sensor_data"],
  "cooling_unit_ids": [],
  "expires_at": "2027-06-08T00:00:00Z",
  "last_used_at": null,
  "revoked": false,
  "created_at": "2026-06-09T10:30:00Z",
  "token": "ctv_live_example_token_shown_once"
}

The token value is returned only at creation time. Coldtivate stores only a SHA-256 hash of the token and cannot recover the raw value later.

Use cooling_unit_ids: [] for company-wide access. To restrict a token to specific cooling units, pass their IDs. All selected cooling units must belong to the token company and must not be deleted:

{
  "cooling_unit_ids": [123, 456]
}

To list token metadata, call:

curl "https://api.coldtivate.org/api/v1/api-tokens" \
  -H "Authorization: Bearer <registered-employee-jwt>"

List and retrieve responses never include the raw token value.

Making Requests

Send the token in the Authorization header using the Bearer scheme.

curl "https://api.coldtivate.org/api/v1/analytics/users?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer <api-token>"

Python example:

import requests

response = requests.get(
    "https://api.coldtivate.org/api/v1/analytics/users",
    headers={"Authorization": "Bearer <api-token>"},
    params={
        "start_date": "2026-01-01",
        "end_date": "2026-01-31",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript example:

const response = await fetch(
  "https://api.coldtivate.org/api/v1/analytics/users?start_date=2026-01-01&end_date=2026-01-31",
  {
    headers: {
      Authorization: "Bearer <api-token>",
    },
  }
);

if (!response.ok) {
  throw new Error(`Analytics request failed: ${response.status}`);
}

const payload = await response.json();
console.log(payload);

Never send API tokens in query parameters, request bodies, logs, or browser-side code.

Scopes

Each token has one or more scopes. Request the minimum scopes needed by your integration.

Scope	Endpoint	Grants access to
`users`	`GET /api/v1/analytics/users`	Aggregated registered user counts, active users, sign-ups, and user breakdowns by cooling unit.
`utilization`	`GET /api/v1/analytics/utilization`	Cooling unit usage, occupancy, check-ins, check-outs, crates and kg stored, and active users by unit.
`revenue`	`GET /api/v1/analytics/revenue`	Revenue totals, revenue by cooling unit, payment method breakdown, trends, and pending payments.
`impact`	`GET /api/v1/analytics/impact`	Food loss prevented, CO2 emissions reduction, income impact, and community served.
`sensor_data`	`GET /api/v1/sensor-data`	Historical cooling unit temperature and humidity readings, including optional hourly or daily aggregation.

Tokens are scoped to a single company. A token cannot access data for another company.

Tokens may also be restricted to specific cooling units inside the company. If cooling_unit_ids is empty, the token has company-wide cooling unit access. If cooling_unit_ids contains IDs, every analytics response is limited to those cooling units.

If a request includes a cooling_unit_id query parameter, that ID must belong to the token company and, for a restricted token, must be included in the token's cooling_unit_ids. Requests for foreign or unallowed cooling units return 404.

Example Analytics Requests

Users:

curl "https://api.coldtivate.org/api/v1/analytics/users?start_date=2026-01-01&end_date=2026-01-31&period=week" \
  -H "Authorization: Bearer <api-token>"

Utilization:

curl "https://api.coldtivate.org/api/v1/analytics/utilization?start_date=2026-01-01&end_date=2026-01-31&cooling_unit_id=123" \
  -H "Authorization: Bearer <api-token>"

Revenue:

curl "https://api.coldtivate.org/api/v1/analytics/revenue?start_date=2026-01-01&end_date=2026-01-31&payment_status=paid" \
  -H "Authorization: Bearer <api-token>"

Impact:

curl "https://api.coldtivate.org/api/v1/analytics/impact?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer <api-token>"

Sensor data:

curl "https://api.coldtivate.org/api/v1/sensor-data?cooling_unit_id=123&specification_type=TEMPERATURE&start_date=2026-01-01&end_date=2026-01-31&aggregation=hourly" \
  -H "Authorization: Bearer <api-token>"

Token Revocation And Regeneration

Revoke a token immediately if it is exposed, no longer needed, or assigned too much access.

Revocation request:

curl -X POST "https://api.coldtivate.org/api/v1/api-tokens/8f1b5d5c-6b61-48f4-a1d8-42f8f8448c38/revoke" \
  -H "Authorization: Bearer <registered-employee-jwt>"

Revocation response:

{
  "id": "8f1b5d5c-6b61-48f4-a1d8-42f8f8448c38",
  "name": "KoldHubs dashboard production",
  "company_id": 42,
  "scopes": ["users", "utilization", "impact", "sensor_data"],
  "cooling_unit_ids": [123, 456],
  "expires_at": "2027-06-08T00:00:00Z",
  "last_used_at": "2026-06-09T12:00:00Z",
  "revoked": true,
  "created_at": "2026-06-09T10:30:00Z"
}

To rotate a token:

Create a replacement token with the same or narrower scopes.
Deploy the new token to your integration.
Confirm requests succeed with the new token.
Revoke the old token.

Error Handling

The API returns JSON error responses. Your integration should handle these status codes explicitly.

401 Unauthorized

Returned when the token is missing, invalid, expired, or revoked.

{
  "detail": "Invalid API token."
}

Recommended action: stop retrying with the same token, alert the integration owner, and generate a replacement token if needed.

403 Forbidden

Returned when the token is valid but does not include the required scope for the endpoint.

{
  "detail": "API token does not include the required scope."
}

Recommended action: request a token with the minimum additional scope required.

429 Too Many Requests

Returned when the token exceeds its rate limit.

{
  "detail": "Request was throttled. Expected available in 42 seconds."
}

Recommended action: back off until the reset time from the rate limit headers.

Rate Limits

The default analytics API limit is:

100 requests per minute per token

Rate limits are currently global per token. Per-scope and partner-tier rate limits are not implemented.

Every analytics response includes rate limit headers:

Header	Meaning
`X-RateLimit-Limit`	The maximum number of requests allowed in the current window.
`X-RateLimit-Remaining`	The number of requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the current window resets.

Example:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 82
X-RateLimit-Reset: 1780905600

Security Checklist

Store API tokens only in a secret manager or secure server-side environment variable.
Do not commit tokens to source control.
Do not expose tokens in browser-side JavaScript or mobile app bundles.
Do not log Authorization headers.
Use the minimum required scopes.
Set an expiry date whenever possible.
Rotate tokens periodically and immediately after suspected exposure.