Use the provider API with least privilege.

Authentication

Send the provider key in the HTTP Authorization header. Never place it in a URL/query, request body, log field, analytics event, source repository, ticket or screenshot.

GET /v1/provider/session HTTP/1.1
Host: panel.nodif.app
Authorization: Bearer <provider-key-from-secret-manager>
Accept: application/json

For command-line testing, inject the key from an approved secret manager into a short-lived process environment variable. Do not paste the value into shell history.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${NODIF_PROVIDER_KEY}" \
  --header "Accept: application/json" \
  https://panel.nodif.app/v1/provider/session

Start with the session capability response

GET /v1/provider/session requires provider:read and returns the current key’s role/scopes, active plan features, subscription state, cohort threshold and raw-event retention policy. It does not return the key ID, token or hashes.

{
  "role": "analyst",
  "scopes": ["provider:read", "analytics:read"],
  "plan": {
    "code": "intelligence",
    "name": "Intelligence",
    "subscription_status": "active"
  },
  "capabilities": {
    "provider_write": false,
    "branding_read": false,
    "branding_write": false,
    "billing_read": false,
    "analytics_read": true,
    "branding_entitled": true,
    "analytics_entitled": true,
    "platform_access": false
  },
  "policy": {
    "minimum_cohort_size": 20,
    "raw_event_retention_days": 30
  }
}

The values above are illustrative. Always use the live response; policy and entitlement can change.

Roles and scopes

Scopes enforce API authorization. Roles are governance labels plus two creation safeguards: owner/admin keys may create keys; only an owner may create another owner. A key cannot grant a scope it does not already hold.

Provider endpoint matrix

Error envelope and incident reference

Non-success responses use a stable code, safe message and request ID. The same ID appears in X-Request-ID.

{
  "error": {
    "code": "insufficient_scope",
    "message": "Provider key does not include the required scope",
    "request_id": "00000000-0000-4000-8000-000000000000"
  }
}

Rate limiting and retries

Provider-authenticated endpoints allow up to 600 requests per minute for the keyed key/source identity. On 429, stop and honor Retry-After: 60. For 500/503, use exponential backoff with jitter and a finite attempt limit. Never retry 401, 403, 409 or schema errors automatically.

Analytics time windows

• Default: the previous seven days ending at server “now”.
• from/to: RFC 3339 timestamps, normalized to UTC.
• Maximum: the active raw-event retention returned by /session.
• to may not be more than five minutes in the future.
• Time series defaults to hourly for windows up to 14 days and daily for longer windows; callers may request hour or day.
• Cohort limit defaults to 50 and accepts 1–200.

GET /v1/provider/analytics/cohorts?from=2026-08-25T00:00:00Z&to=2026-09-01T00:00:00Z&dimension=platform&limit=50

Safe key rotation

1. Create a replacement with the minimum role/scopes.
2. Store plaintext immediately in the approved secret manager.
3. Test /v1/provider/session and one required read endpoint.
4. Update one automation/portal operator at a time.
5. Confirm last_used_at on the replacement.
6. Revoke the old key from a different active owner/admin key.
7. Remove old secret references and document only key label/ID—not plaintext.

Rotate immediately after disclosure, staff departure, device loss, unexpected use or a scope change. Never solve access problems by sharing the owner key.