Authentication & Access

Every Tuned Global API endpoint requires an authenticated request. Which authentication scheme you use depends on the API you're calling and what it accesses so it's worth understanding different security models before you integrate. There are four security models availalbe.

Authentication methods

Tuned Global supports four authentication methods. Most integrations only ever need the ‘API Key’ and oAuth 2.0 Authentication.

API Key Authentication

A static key that identifies your store on every request. Required everywhere, no matter which other security method also applies.Add description here

oAuth 2.0 Authentication

A short-lived access token for a signed-in user. Required for anything done on that user's behalf: their library, playback, votes, or playlists.

Basic HTTP Authentication

A partner access key and secret, issued directly by Tuned Global, sent as a Base64-encoded credential. Used only for a small set of partner and telco integration endpoints. This is not a user login method.

HMAC Authentication

A cryptographically signed request. Used only for specific integrations: device and guest registration, telco partner endpoints, and large-scale asset delivery.

Choosing the right method for your API family

Tuned Global provides three API families, each designed for a different integration purpose and protected by the appropriate security model:

If you are building a typical web or mobile app that lets people browse the catalogue and manage their own library, you need exactly two things: an API key, and an OAuth token to sign the user in and fetch relevant metadata.

Getting a user access token

Services ​APIs act on behalf of an individual user, so most requests need an OAuth 2.0 bearer token in addition to your StoreId. There are four ways to obtain one:

1. Email login.​ Authenticate with a username and password.
2. Mobile login.​ Authenticate with a one-time passcode sent to a phone number.
3. Refresh token.​ Exchange a previously issued refresh token for a new access token, without asking the user to sign in again.
4. Third-party JWT.​ Exchange a JWT you have already issued and signed for a Tuned Global access token. Tuned Global verifies it against a public key held for your store.

Access tokens are short-lived and paired with a longer-lived refresh token, so you can keep a user's session alive without repeated logins. See oAuth 2.0 Authentication for request and response examples for each method.

Basic authentication and HMAC signing

These two methods exist for specific integrations, not general app development.

Basic HTTP authentication​ is for partner and telco integrations: things like managing a shared allowlist of catalogue content, or submitting play logs in bulk. The credentials are an access key and secret issued to that partner by Tuned Global, not an end user's login.

HMAC request signing​ is required for a small number of flows: registering a device or guest session on the Services API, telco partner integrations, and asset or catalogue delivery through the Catalogue Feed API. If none of these apply to your integration, you will not need it.

Integration checklist

• Include the ​StoreId​ ​header on every request, regardless of API family.
• Use Metadata APIs with ​StoreId​ ​only. No user token is required.
• Use Services APIs with ​StoreId​ ​plus a valid OAuth bearer token for anything done on behalf of a signed-in user.
• Treat API keys, partner credentials, and tokens as secrets. Do not commit them to source control or expose them in client-side code.
• A missing or invalid credential will cause the request to be rejected.