Skip to content
HooprB2B
Access

Operations

Best practices

A curated guide to building an integration that is fast, resilient, and secure against the Hoopr B2B API.

Token handling

  • Cache the access token until ~5 minutes before expiry — a token is a JWT that lives one hour.
  • One token serves many calls; do not mint a fresh token per request.
  • On 401 invalid_token, refresh once and retry the call.

Caching the catalog

  • Cache track metadata freely — names, BPM, filters, and artists rarely change.
  • Cap any cache holding a streamUrl at 30 minutes max so a signed URL never outlives its signature. See The track object.
  • artworkUrl is a stable CDN link you can cache long-term.

Resilience

  • Use exponential backoff on 429 and 503 — read RateLimit-Reset to time your retry.
  • Treat unknown JSON fields as forward-compatible; new optional fields ship without a version bump, so don’t break on them. See Versioning.

Security

  • Keep client_secret server-side only — all calls are server-to-server.
  • Rotate the secret immediately if it leaks.
  • Never expose tokens to browsers or mobile apps.

Efficiency

  • Prefer filterSlugs / filterIds and tuned pageSize over fetching the whole catalog.
  • Call GET /v1/filters once and cache the filter list rather than re-fetching it per query.

A robust integration in one paragraph

Mint one access token, cache it until five minutes before expiry, and refresh once on 401 invalid_token. Fetch the filter list once and cache it, then query /v1/tracks with filterSlugs and a sensible pageSize instead of paging the whole catalog. Cache metadata long-term but never hold a streamUrl past 30 minutes. Keep the secret server-side, back off exponentially on 429/503, and ignore unknown JSON fields so new releases never break you.

PreviousRate limitsNext Roadmap