Beat Technology Core API Documentation (2.0.0)

This section collects conventions that apply across the entire API — who typically consumes it, the URL and encoding rules all endpoints agree on, how pagination works, which custom HTTP headers are supported, and how errors are returned. Read this once before diving into specific endpoints; individual operation references assume you are familiar with everything described here.

The API is shared by three distinct categories of caller, and some endpoints or authorization rules are written with a specific category in mind:

1. End-user apps (customers) — web frontends, mobile apps, and set-top boxes. These run in either visitor or authenticated-user mode.
2. Backoffice app — the internal support tooling.
3. Partner integrations — server-to-server callers that manage subscriptions on behalf of end users (see the Subscription management walkthrough).

All resources live under a versioned path on a tenant-specific host:

https://api.prod.{tenant}.beat.no/v2/{resource}

{tenant} is the short identifier for the Beat deployment you are integrating with (for example fabel, skoobe). All current endpoints are served under /v2/; older versions are not supported.

Both request and response bodies are UTF-8 encoded.

Content-Type

The OAuth 2.0 token endpoint (/v2/oauth2/*) expects application/x-www-form-urlencoded bodies, as required by the OAuth spec. Every other /v2/* endpoint exchanges JSON: send Content-Type: application/json on any POST, PUT, or PATCH and encode the body with JSON.stringify or your language's equivalent. Do not rely on the browser's default application/x-www-form-urlencoded for JSON endpoints — it will be rejected.

id — string

Every resource has a unique id. Even when the value looks like a number, it is always a string in both requests and responses. Parse it as a string on the client side; JavaScript's Number silently loses precision on large integer values.

date — string

UTC, in the form YYYY-MM-DD (e.g. 1997-07-16).

datetime — string

UTC, in the form YYYY-MM-DDThh:mm:ssTZD (e.g. 1997-07-16T19:20:30Z), compliant with http://www.w3.org/TR/NOTE-datetime.

Where:

• YYYY — four-digit year
• MM — two-digit month (01 = January, …)
• DD — two-digit day of month (01–31)
• hh — two digits of hour (00–23), 24-hour clock
• mm — two digits of minute (00–59)
• ss — two digits of second (00–59)
• TZD — time zone designator, always Z

No decimal fraction of a second is used, and +hh:mm / -hh:mm offsets are not accepted — only Z.

url — string

Fully qualified URLs only.

• URL/URI path segments and query parameters: lower case, underscores.
• JSON property names: lower case, underscores.

List and search results are paginated using HTTP Range headers with a custom range unit that depends on the resource (for example tracks on track searches, products on product listings).

Relevant RFC sections:

• 3.12 Range Units
• 14.5 Accept-Ranges
• 14.16 Content-Range
• 14.35 Range

Defaults: offset 0; page sizes are one of 10, 20, 100, 200, or 1000 items, resource-dependent.

Note the asymmetric spelling between request and response required by the RFC: the Range request header uses =, the Content-Range response header uses a space:

Range: tracks=0-49
Content-Range: tracks 0-49

Key points from RFC 2616 §14.16:

• Format: unit SP first-pos "-" last-pos "/" (instance-length | "*").
• A 416 Requested Range Not Satisfiable response SHOULD include Content-Range with * as the range.
• A 206 Partial Content response MUST NOT include Content-Range with *.
• instance-length is the total number of accessible items in the collection.

A next page exists when instance-length > last-pos + 1. The body may contain fewer items than last-pos - first-pos + 1, even on 206 responses — Content-Range always reflects the requested range, not the number of items delivered.

Examples

First 20 tracks (the default window):

$ curl "https://api.prod.$TENANT.beat.no/v2/tracks?query=gaga" \
    -H "Authorization: Bearer $TOKEN"

HTTP/1.1 206 Partial Content
Accept-Ranges: tracks
Content-Range: tracks 0-19/21          # 21 > 19+1 → next page exists

Second page, items 20–39 inclusive:

$ curl "https://api.prod.$TENANT.beat.no/v2/tracks?query=gaga" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Range: tracks=20-39"

Out-of-range request:

$ curl "https://api.prod.$TENANT.beat.no/v2/tracks?query=gaga" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Range: tracks=1000-999"

HTTP/1.1 416 Requested Range Not Satisfiable

Beat defines a small set of optional X-* request headers that let a client fine-tune what data comes back without changing the URL. All are optional; defaults are tenant-specific.

Content selection

X-Include

Request additional sub-objects to be embedded in the response. The value is a comma-separated list; valid names are:

• release-reviews
• release-tracks
• release-notes
• release-prices
• track-prices
• group-releases
• group-banners

Image size headers

Several resources return image references whose concrete sizes are chosen per request: the client sends a header describing the sizes it wants, and the response embeds only those. See each object's Basic response objects section for the accepted size syntax.

X-Release-Cover-Sizes

Specifies sizes for release cover images.

X-Artist-Image-Sizes

Specifies sizes for artist images.

X-Actor-Image-Sizes

Specifies sizes for actor images.

Stream selection

X-Stream-Formats

Selects the stream quality returned for audio/video resources. The value is a comma-separated list of format names. Valid names are:

• */high
• */normal
• */low
• h264/*

Supply the values you receive in the streams object of a Track Extended response; see GET /v2/tracks/{track_id} for details. Used by GET /v2/streams/online and GET /v2/streams/offline.

X-Stream-Context

Stream URLs normally require a user access token and an active subscription. In some tenant-specific configurations a stream URL can be fetched based on a different context — for example a promotional clip attached to an entity. Supply the header as X-Stream-Context: <entity_type>/<entity_id>.

Response bodies are JSON-encoded.

Format conventions

The root of every response is an object (never a bare array), and keys at the root act as a namespace:

{"tracks": [{"track": {"...": "..."}}]}   // no: over-nested
{"tracks": [{"...": "..."}]}              // yes
{"title": "value"}                        // no: missing namespace
{"track": {"title": "value"}}             // yes

HTTP error codes

• 400 Bad Request — invalid input. The error message indicates which parameter and why.
• 401 Unauthorized — bad or expired access token. Re-authenticate the user and retry.
• 403 Forbidden — request rejected by authorization, e.g. missing role or invalid OAuth signature.
• 404 Not Found — the requested resource does not exist.
• 405 Method Not Allowed — HTTP method not supported on this endpoint.
• 5xx — server error. Check the status page or file a bug.

Error response body

All non-success responses share the same body shape:

{
  "error": "exception",
  "error_description": "Human-readable description",
  "error_developer": { }
}

error and error_description are always present. error_developer is an optional object with extra debugging context — safe to log, not safe to surface to end users.

The API supports Cross-Origin Resource Sharing (CORS) for AJAX requests. Any domain registered as an OAuth application is accepted as an origin.

Plain request from an unregistered origin:

$ curl -i "https://api.beat.no" -H 'Origin: http://example.com'
HTTP/1.1 302 Found
Location: https://developer.beat.no

Request from a registered origin (e.g. the beat.no web app):

$ curl -i "https://api.beat.no" -H 'Origin: http://beat.no'
HTTP/1.1 302 Found
Location: https://developer.beat.no
Access-Control-Allow-Origin: http://beat.no
Access-Control-Expose-Headers: Content-Range, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
Access-Control-Allow-Credentials: true

CORS preflight:

$ curl -i "https://api.beat.no" -H 'Origin: http://beat.no' -X OPTIONS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://beat.no
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, X-Release-Cover-Sizes, X-Artist-Image-Sizes, X-Stream-Formats, Authorization, Range
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: Content-Range, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true

This article walks a partner integration through the full subscription lifecycle on a Beat tenant: obtaining an app access token, validating the user's e-mail, creating the user, attaching a payment method, activating a subscription, and finally stopping or deactivating it. Every step shows a runnable curl example with the headers a real client must send. For the full request/response schema of each endpoint, follow the link in each step's heading to the operation reference.

Throughout the examples, $TENANT is the tenant identifier (part of the API host name), and $TOKEN is the currently active access token. Re-export $TOKEN whenever a new step switches between a client access token (steps 1–3) and a user access token (steps 4 onwards).

Most subscription-management calls run on behalf of the partner itself (no end-user context), so authenticate with the client_credentials grant type using the OAuth 2.0 token endpoint (POST /v2/oauth2/token).

$ export TENANT=
$ export CLIENT_ID=
$ export CLIENT_SECRET=

$ curl -X POST "https://api.prod.$TENANT.beat.no/v2/oauth2/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "client_id=$CLIENT_ID" \
    --data-urlencode "client_secret=$CLIENT_SECRET"

Successful response (200 OK):

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "expires_in": 3600,
  "token_type": "bearer"
}

Store the returned access_token as $TOKEN. Tokens expire — re-issue when expires_in elapses.

Before creating the user account, verify that the e-mail address actually belongs to the person signing up. Submit the e-mail via POST /v2/credentials; the backend stores it as a pending credential and dispatches a one-time verification code by e-mail.

$ curl -X POST "https://api.prod.$TENANT.beat.no/v2/credentials" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
          "type": 8,
          "credential": "user@example.com"
        }'

A successful call returns 202 Accepted with an empty body. Type 8 is the regular user e-mail credential.

Internally this emits a user.credential_verification_requested event which carries the verification code and is typically forwarded to your mail delivery system (for example Vero) to hand the code to the user — either as a code they type back into your signup form, or encoded in a magic-link URL. You must capture that code from the user before the next step and pass it as email_token when creating the account.

With the verification code in hand, create the user via POST /v2/users. The only required fields are email, email_token, and password; username is strongly recommended to match the e-mail address.

⚠️ Always use the client-credentials $TOKEN here. If you call POST /v2/users with a user access token, the new account is created as a profile-user of the authenticated user, which will make every subsequent subscription call fail in non-obvious ways.

$ curl -X POST "https://api.prod.$TENANT.beat.no/v2/users" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
          "username": "user@example.com",
          "email": "user@example.com",
          "email_token": "<verification code from step 2>",
          "password": "<user-chosen password>"
        }'

Successful response (201 Created):

{
  "user": {
    "id": "28392",
    "username": "user@example.com"
  }
}

Note the id — this is the $USER_ID used in all later steps. Optional fields such as firstname, lastname, and newsletter can be supplied in the same body; see the POST /v2/users reference for the full schema. If the e-mail is already taken, the response is 409 Conflict.

Steps 5 and 6 (attaching a payment method and listing products) run on behalf of the user, not the partner, and therefore need a user access token. Exchange the user's e-mail and password for one using the password grant type.

$ export USERNAME=user@example.com
$ export PASSWORD=<user-chosen password>

$ curl -X POST "https://api.prod.$TENANT.beat.no/v2/oauth2/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=password" \
    --data-urlencode "client_id=$CLIENT_ID" \
    --data-urlencode "client_secret=$CLIENT_SECRET" \
    --data-urlencode "username=$USERNAME" \
    --data-urlencode "password=$PASSWORD"

Response (200 OK):

{
  "access_token": "7924bef2b848a895...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "b3aa9e0c635923...",
  "user_id": "28392"
}

Re-export $TOKEN to the returned access_token and store the refresh_token securely — it lets the user stay signed in without re-prompting for the password. See the Authentication tag for refresh-token handling and OIDC-based sign-in.

Subscriptions are billed against a stored payment method. Attaching one is a two-step flow: create a setup intent, then — once the client has tokenized the card — attach the resulting reference to the user.

5a. Create a setup intent

Call POST /v2/billing/setupintents with the payment type (3 for Stripe, 4 for Billwerk / Reepay) and the product the user intends to subscribe to.

$ curl -X POST "https://api.prod.$TENANT.beat.no/v2/billing/setupintents" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
          "payment_type": 3,
          "product_id": "201"
        }'

Response (200 OK):

{
  "client_secret": "seti_dadd3b3c4989acb6f0ff1044a50b0974",
  "setup_intent": {
    "payment_type": 3,
    "client_secret": "seti_dadd3b3c4989acb6f0ff1044a50b0974"
  }
}

Use the top-level client_secret (the nested setup_intent.client_secret is deprecated but kept for backwards compatibility).

Hand this client_secret to the client-side payment SDK — Stripe Payment/Express/Card Elements for Stripe, or a redirect to the hosted Billwerk checkout at https://checkout.reepay.com/#/<client_secret> for Billwerk — to collect card details. The SDK integration itself is out of scope for this walkthrough; refer to the provider's documentation. For Billwerk flows, also supply redirect_url and cancel_url in the setup intent request; the user will be redirected to one of these when the hosted checkout finishes.

5b. Look up the tokenized reference

After tokenization Stripe will return a payment-method identifier (pm_...) on the client side. Do not attach that identifier directly. Instead, look it up through Beat's backend, keyed by the setup intent id:

$ curl "https://api.prod.$TENANT.beat.no/v2/billing/paymentmethods?setupintent=seti_dadd3b3c4989acb6f0ff1044a50b0974" \
    -H "Authorization: Bearer $TOKEN"

Response (200 OK):

[
  { "reference": "pm_asdf9023jmkasdf02jkasdf" }
]

Some payment types allow the initial-setup payment method to be replaced by a different method downstream; going through Beat's backend ensures you pick up the correct final reference.

For Billwerk flows, the reference is delivered as the payment_method query parameter on the success-redirect URL instead, so this lookup call can be skipped.

5c. Attach the payment method to the user

$ curl -X POST "https://api.prod.$TENANT.beat.no/v2/billing/paymentmethods" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
          "payment_type": 3,
          "reference": "pm_asdf9023jmkasdf02jkasdf"
        }'

A 200 OK response means the user's account is now linked to the payment provider. Any active subscription is also migrated to the new provider at this point.

Look up the catalog of products this client is allowed to subscribe users to via GET /v2/products.

$ curl "https://api.prod.$TENANT.beat.no/v2/products" \
    -H "Authorization: Bearer $TOKEN"

For large catalogs, paginate with the Range header:

$ curl "https://api.prod.$TENANT.beat.no/v2/products" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Range: products=20-39"

Pick the product_id you intend to activate.

Activate the chosen product for the user via POST /v2/users/{user_id}/migrations. Pass renewable=false to disable auto-renewal.

$ export USER_ID=28392

$ curl -X POST "https://api.prod.$TENANT.beat.no/v2/users/$USER_ID/migrations" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
          "product_id": "201",
          "renewable": true,
          "confirmed": true
        }'

A 201 Created response means the subscription is live; it should be visible in Backoffice and in the connected payment provider (Stripe, Billwerk, etc.).

Inspect a user's current subscriptions via GET /v2/users/{user_id}/subscriptions.

$ curl "https://api.prod.$TENANT.beat.no/v2/users/$USER_ID/subscriptions" \
    -H "Authorization: Bearer $TOKEN"

Response (206 Partial Content):

{
  "subscriptions": [
    {
      "id": "9001",
      "product_id": "201",
      "state": 3,
      "expiry_date": "2026-05-01T00:00:00Z"
    }
  ]
}

Note the id of the subscription you want to stop or deactivate.

Toggle a running subscription's renewal state via PATCH /v2/users/{user_id}/subscriptions/{subscription_id}. Pass state=6 to stop (the subscription will expire at the end of the current period) or state=3 to resume a previously stopped subscription.

$ export SUBSCRIPTION_ID=9001

$ curl -X PATCH "https://api.prod.$TENANT.beat.no/v2/users/$USER_ID/subscriptions/$SUBSCRIPTION_ID" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "state": 6 }'

Response (200 OK):

{
  "subscription": {
    "expiry_date": "2026-05-01T00:00:00Z",
    "next_billing_date": null,
    "state": 6
  }
}

To end a subscription right away rather than letting it expire naturally, use DELETE /v2/users/{user_id}/subscriptions/{subscription_id}.

$ curl -X DELETE "https://api.prod.$TENANT.beat.no/v2/users/$USER_ID/subscriptions/$SUBSCRIPTION_ID" \
    -H "Authorization: Bearer $TOKEN"

A 200 OK response confirms the subscription is deactivated.

• See the Authentication tag for all supported OAuth grant types, refresh-token handling, and OIDC sign-in.
• See the User tag for full schemas of the user, credential, migration, and subscription operations referenced above.
• See the Billing tag for the full setup-intent and payment-method schemas, including Billwerk-specific fields.
• For partner-specific user-management endpoints (separate, header-based auth), see the Partner users tag.

Operations around actors

Operations around artists

API implements OAuth 2.0 protocol for authentication.

Each request to API resources requires an access_token. There are a few ways to get access token depending on client type.

Mobile Apps or Web Apps use authentication by username/password.

Access Tokens

• User Access Token — token associated with a user id, requested by one of:
  • grant_type=password
  • grant_type=clone_token
  • grant_type=signed_msisdn
  • grant_type=coupon
  • grant_type=verification_code
  • grant_type=account_user
  • grant_type=openid_handle
• App Access Token — token not associated with any user, requested by:
  • grant_type=client_credentials

User Tokens

IMPORTANT. The duration of access_token, refresh_token, scope is unspecified and can be changed at any time. So clients have to expect any duration at any moment in the future (i.e. data type should be considered as a TEXT in terms of SQL).

Authentication by User Password (grant_type=password)

Flow: 4.3 Resource Owner Password Credentials Grant.

NOTE: Authentication by user password is an exceptional case and such flow should only be enabled for selected applications. All other the third-party applications MUST use another ways described below.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=password
  &username=<msisdn|email>
  &password=<password>
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example",                     // bearer
    "scope": ""                                 // optional
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWI",    // optional
    "user_id":"5667asdf"                        // optional, beat user id - included if access_token generated for
                                                // authenticated user
  }

Authentication by Signed MSISDN (grant_type=signed_msisdn)

Issue new access token based on signed MSISDN. Used to support Web App's passwordless login for Gakk Media (Robi Web App and others).

SECURITY NOTE: Enabled for Bangladesh phone numbers only at the moment. SECURITY NOTE: Signature can only be generated by nginx based on specific authorization headers provided by carrier's networks. It makes possible to login to the app without typing of password. See nginx configuration for signature generation procedure.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=signed_msisdn
  &msisdn=8801600000199
  &msisdn_signature=87r1uhasdyfp13jskfd
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "user_id":"5667asdf" // beat user id
  }

[DEPRECATED] Authentication by coupon code (grant_type=coupon)

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=coupon
  &code=test1
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "user_id":"5667asdf" // beat user id
  }

Authentication by verification code (grant_type=verification_code)

Code can be generated and optionally send to customer by POST v2/codes.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=verification_code
  &msisdn=0029133437595305 // optional, one of msisdn or user_id should present
  &user_id=1111 // optional, one of msisdn or user_id should present
  &code=1234
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "user_id":"5667asdf" // beat user id
  }

Cross-client Authentication (grant_type=clone_token)

Clone user token for the usage by the new client.

The grant_type=clone_token can be used to issue new access_token for the new client based on access_token issued by the different client (both clients are from the same project). The new issued access_token will always have the same associated user_id.

NOTE: Use grant_type=refresh_token to issue access_token for the same client.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=clone_token
  &access_token=2YotnFZFEjr1zCsicMWpAA // access token issued with another client credentials from the same project
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET

Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"087fashf34h7adysfy", // new token with the same user_id
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "" // optional
    "refresh_token":"dfq4lajw78152345sfga", // optional
    "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
  }

Switching between account users (profiles) (grant_type=account_user)

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=account_user
  &access_token=<access_token> // access token of one of account users (profiles)
  &user_id=<target_user_id> // id of target profile-user within the same account
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"087fashf34h7adysfy", // new token with the same user_id
  "expires_in":3600,
  "token_type":"example", // bearer
  "scope": "" // optional
  "refresh_token":"dfq4lajw78152345sfga", // optional
  "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
}

Authentication by OpenID auth session handle (grant_type=openid_handle)

This option is used to authenticate by a previously-started OpenID session. The handle is a value that retrieved during the first step of this process. Use this call only after the OpenID callback is finished.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=openid_handle
  &handle=<handle>
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "" // optional
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", // optional\_
    "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
  }

App Tokens

App tokens are used to make requirests to Beat APIs on behalf of an app rather than a user. This can be useful to provide "visitor mode" in the apps.

Authentication by Client Credentials (grant_type=client_credentials)

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=client_credentials
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET
  
Response (the same as for grant_type=password):
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "", // optional
    // NOTE: no refresh_token field
  }

Refreshing Tokens (grant_type=refresh_token)

Access tokens have a limited lifetime and can be refreshed when required without asking the user to login again to get new token.

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=refresh_token
  &refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET

Response (the same as for grant_type=password):
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
    "token_type":"example", // bearer
    "scope": "", // optional
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" // optional
  }

Install Referrer support

Introduced mainly to support Google Play Install Referrer API.

There is an optional parameter to help tracking of install events. When user logs in to the app, client app may specify install_referrer string param provided by Google Play services.

IMPORTANT FOR CLIENTS: App should add install_referrer param only once and must clean it on after successful log in, so repeated log ins should not be tracked/rewarded.

Example:

Request:
  POST /v2/oauth2/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=password
  &username=johndoe
  &password=A3ddj3w
  &client_id=APPLICATION_ID
  &client_secret=APPLICATION_SECRET,
  &install_referrer=u_12345
  
Response:
  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
      "access_token":"2YotnFZFEjr1zCsicMWpAA",
      "expires_in":3600,
      "token_type":"example", // bearer
      "scope": "" // optional
      "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", // optional
      "user_id":"5667asdf" // optional, beat user id - included if access_token generated for authenticated user
  }

Every operation documents the access level its caller must have. This page explains each access level. For how to obtain a bearer token, see the Authentication API article.

Access levels are not a strict hierarchy. An editorial admin is not automatically a logged-in user, and a user admin client using the client_credentials grant has no end-user identity at all. Each endpoint states plainly which level (or levels) it accepts.

Public

The endpoint can be called without credentials. Used by token endpoints, OpenID login callbacks, and webhooks. Webhook endpoints are public at the transport layer but verify request authenticity out-of-band (e.g. a signed payload from the payment provider).

Prose line: **Authorization:** Public — no credentials required.

Any valid bearer token

A bearer token is required, but it does not need to belong to a logged-in user. App-only tokens obtained via grant_type=client_credentials (also called "visitor" tokens) are accepted, as are tokens obtained from any other grant. Used by browse/search endpoints and other read operations that do not depend on a user identity.

Prose line: **Authorization:** Any valid bearer token (app-only / visitor tokens are accepted).

Logged-in user

The bearer token must belong to an end-user — i.e. it must have been obtained from one of the user-binding grants (password, clone_token, verification_code, etc.) and carry a user_id. Used by any endpoint that operates on "the authenticated user's own" data.

Prose line: **Authorization:** Logged-in user required.

Editorial admin

The bearer token must belong to a user that is registered as editorial staff. Used by endpoints that manage catalog content — patching series, uploading cover images, reordering featured artists, and so on.

Prose line: **Authorization:** Editorial admin only.

User admin client

The caller must use grant_type=client_credentials with a client that is registered as a user-administration client. Used by partner-integration endpoints that manage end-user accounts on behalf of the partner (GDPR deletion, user lookup by email/msisdn, privileged user creation).

Prose line: **Authorization:** User admin client only.

Partner credentials

Partner-integration endpoints under /v2/partnerusers/* authenticate with a shared client-id / client-secret pair sent as headers instead of a bearer token.

Prose line: **Authorization:** Partner credentials required (X-Auth-Client-Id and X-Auth-Client-Secret).

Scope-gated bearer token

A small number of endpoints require a bearer token that was issued with a specific OAuth scope. The scopes in use are statistics and external-charge. Any underlying grant is accepted as long as the token carries the scope.

Prose line: **Authorization:** Bearer token with the \statistics` scope.(or`external-charge``).

HTTP Basic

Used by a single endpoint (GET /v2/lcp/license/status/...) that is called by Readium LCP servers which cannot present OAuth tokens. Credentials are provisioned out-of-band with the LCP provider.

Prose line: **Authorization:** HTTP Basic auth (LCP provider credentials).

Some endpoints accept more than one access level (for example, "the user themselves, or a user admin client"). Those operations list the alternatives on one line:

**Authorization:** Logged-in user, or user admin client.

A few endpoints — most notably GET /v2/users — accept different callers depending on which query parameters are set. These operations show:

**Authorization:** Varies by query parameter — see the parameter descriptions.

and each query parameter that raises the baseline has its own **Authorization:** line in that parameter's description. A parameter with no such line inherits the operation's baseline.

Banner operations