Skip to content
HooprB2B
Access

Get started

Authentication

The API uses the OAuth2 client-credentials grant. You exchange a client_id / client_secret for a short-lived Bearer access token, then send that token on every call.

1 · Authenticate

POST your client_id + client_secret to /v1/auth/token. Receive a 1-hour Bearer access token.

2 · Call the API

Send the token as Authorization: Bearer on every catalog request. The token's mode (test/live) is bound to the secret used.

3 · Get music

Browse, search, and fetch tracks, playlists & filters. Stream via short-lived signed URLs.

Credentials

Your account manager issues two values:

  • client_id — a public UUID identifying your client.
  • client_secret — a secret string. Store it securely; it is shown only once at creation.

Never expose the secret client-side

All API calls are server-to-server. Do not embed client_secret in a browser, mobile app, or any client-side code. If a secret leaks, ask us to rotate it.

Get an access token

POST your credentials to the token endpoint. Tokens are JWTs that live one hour — cache and reuse a token until it nears expiry, then request a new one.

curl -X POST https://<host>/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<client_id>",
    "client_secret": "<client_secret>"
  }'
{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "catalog:read search",
    "mode": "test"
  },
  "error": { "code": 0, "message": "Token issued" }
}

Use the token

Send it as a Bearer token on every other request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Scopes

Your client is granted one or more scopes. Calling an endpoint without the required scope returns 403 insufficient_scope.

ScopeGrants access to
catalog:readList/fetch tracks, playlists, filters
searchPOST /v1/search
analytics:readGET /v1/tracks-top

Token lifecycle

Caching & refresh

  • Cache the access token until ~5 minutes before expires_in, then refresh.
  • On 401 invalid_token, fetch a new token once and retry the call.
  • Token requests are rate-limited to 30/minute per client — don’t request a fresh token per API call.

Mode is bound to the secret

The token’s mode (test/live) is decided by the secret you used, and echoed in the response (mode) and the X-Hoopr-Mode response header. See Test & live mode.

PreviousQuickstartNext Test & live mode