Skip to main content

Authentication

You have four different methods offered for member identification. The first three exchange the user's credentials for a token you use in subsequent calls; the fourth (HTTP Basic) lets the user's client authenticate on every request with their login and password directly.

OAuth 2.0​

This is the most recommended method, compatible with OAuth 2.0 libraries available in most languages.

Send the user to the authorization page where they must log in:

https://www.betaseries.com/authorize

With the following GET parameters:

  • client_id: Your API key.
  • redirect_uri: The URI to redirect the client to process the authorization code.

Once the client is identified, they are redirected to redirect_uri with the GET parameter code. On this page, you must call the API to retrieve the user token:

POST https://api.betaseries.com/oauth/access_token

With the following POST parameters:

  • client_id: Your API key.
  • client_secret: The secret key provided in your key information.
  • redirect_uri: The callback address you had already provided for the first part.
  • code: Code retrieved by the first part of the identification.

The API then returns the user token in this form:

access_token=42284998e2ce

Identification by code​

If your application is installed on a device with limited writing capabilities (like a television), it is possible for you to offer your user to identify themselves by typing a code on another device, like their smartphone or computer.

For this, you must first call the method /oauth/device to have the information to display to your user:

POST https://api.betaseries.com/oauth/device

The return will be similar to this:

{
    "device_code": "1c2b45bb95ca670a2fca54ddc9a58b63",
    "expires_in": 1800,
    "interval": 5,
    "user_code": "975-820",
    "verification_url": "https://www.betaseries.com/device"
}

You must display the user_code to your user, indicating to go to verification_url. Meanwhile, your application must periodically call (here every 5 seconds) the API method oauth/access_token waiting for identification.

POST https://api.betaseries.com/oauth/access_token

With the following POST parameters:

  • client_id: Your API key.
  • client_secret: The secret key provided in your key information.
  • code: The device_code returned in the previous method.

As soon as your user is identified, a token will be returned, and you can use the API with their account.

Similar to OAuth​

A simpler but non-conventional version of OAuth. First, you must retrieve a key necessary for identification via the API:

POST https://api.betaseries.com/members/oauth

Once the key is retrieved, send your user to the identification page:

https://www.betaseries.com/oauth?key=XXXXXXXX

If the identification is successful, the user will be redirected to the callback URL you configured for the key, with the token as a GET parameter.

Basic identification​

This is the first proposed identification, which still works but should always be used in HTTPS since the username and password are sent in the same request.

POST https://api.betaseries.com/members/auth

With the following POST parameters:

  • login: User name or email address
  • password: Password encrypted in MD5

The API then returns the information of the identified member as well as the token you just created.

HTTP Basic authentication​

For scenarios where you want the end user to be able to rotate their credentials themselves without depending on a token (for example third‑party integrations shipped to end users, such as home‑automation plugins, personal dashboards, or scripts), the API also accepts standard HTTP Basic authentication on any request.

Authorization: Basic <base64(login:password)>

The password can be provided either in plain text or in MD5. HTTPS is mandatory — the credentials are sent on every request.

Example with curl:

curl -H 'X-BetaSeries-Key: <your_api_key>' \
     -H 'X-BetaSeries-Version: 3.3' \
     -u 'my_login:my_password' \
     https://api.betaseries.com/members/infos

If authentication succeeds, the member is set for the current request and the response is identical to what a token‑authenticated request would return. If credentials are invalid, the request is treated as unauthenticated (no error is raised specifically for the failed Basic attempt).

This mode is convenient for one‑off scripts and end‑user integrations. It is not a replacement for the token flows above, which remain the recommended approach whenever the caller can persist an opaque, revocable token.