Authentication

The Streamdiver API uses the OAuth 2.0 protocol for authentication and authorization with the client credentials grant flow. It permits a web service to use its own credentials and is commonly used in server-to-server interactions, with no user involved in the authentication. The required clientId and clientSecret are shared during initial tenant creation and must be kept safe.

Given the clientId and secret your application requests an access token from the Streamdiver authorization server at https://sso.streamdiver.com. The token can then be extracted from the response and used to authenticate further requests against protected resources in the Streamdiver API. The tokens by default have a session lifetime of 16 hours.

Note: Refresh tokens will not be granted with this flow as clientId and clientSecret can be used to obtain an access token right away.

Get a Token

A token can be retrieved with a POST request against the Streamdiver authorization server. Given a tenant has been setup, obtaining the token requires:

Parameter	Description
tenantShortcode	Abbreviated and unique version of the tenant name assigned during onboarding.
clientId	Application identification value that has been assigned during onboarding.
clientSecret	Secret used by a client (application) to authenticate with the authorization server, it is known only the client and the authorization server.

These credentials are obtained during initial tenant creation, if you are unsure or missing information contact our support.

Token endpoint: https://sso.streamdiver.com/realms/{tenantShortcode}/protocol/openid-connect/token

To request a token:

curl

curl --request POST \
    --url https://sso.streamdiver.com/realms/{tenantShortcode}/protocol/openid-connect/token \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id={clientId} \
    --data client_secret={clientSecret}

Python

import requests

response = requests.post(
    "https://sso.streamdiver.com/realms/{tenantShortcode}/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "{clientId}",
        "client_secret": "{clientSecret}",
    },
)
token_data = response.json()
access_token = token_data["access_token"]

TypeScript

const response = await fetch(
  "https://sso.streamdiver.com/realms/{tenantShortcode}/protocol/openid-connect/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: "{clientId}",
      client_secret: "{clientSecret}",
    }),
  }
);
const { access_token: accessToken } = await response.json();

Expected response:

{
    "access_token":"eyJ...sAQ",
    "expires_in":7200,
    "refresh_expires_in":0,
    "token_type":"Bearer",
    "not-before-policy":0,
    "scope":"email profile"
}

Use a Token

Authentication against the Streamdiver API is performed with Bearer authentication. Similar to Basic authentication, Bearer authentication should only be performed over HTTPS. The token retrieved earlier must be sent in the Authorization header.

curl

curl --request GET \
    --url https://api.streamdiver.com/v2/tenants/current/settings \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json'

Python

response = requests.get(
    "https://api.streamdiver.com/v2/tenants/current/settings",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
)
settings = response.json()

TypeScript

const settings = await fetch(
  "https://api.streamdiver.com/v2/tenants/current/settings",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
  }
).then((r) => r.json());