Authentication

Basically, authentication on Ubstream allows users to acquire Access Tokens as JWT format using openid-connect protocol which is an authentication layer on top of OAuth 2.0. Access Tokens invalidate after 1 minute, and have to be renewed with Refresh Tokens.

Once retrieved, an Access Token will allow to perform some action on the platform

To perform a login action and get a valid Access Token we need to send a POST request to the login endpoint.

Password can be replaced by an API key.

POST /api/v1/auth/login HTTP/1.1
Host: developer.ubstream.com
Content-Type: application/json

cURL example:

curl -X POST "https://developer.ubstream.com/api/v1/auth/login" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{  \"username\": \"developer-api-demo\",  \"password\": \"XXXXXXX\"}"

If successful, the response will have a Status Code 200 (OK) and contain the following attributes as JSON format:

access_token: The Access Token as JWT
expires_in: A number in seconds describing how long the Access Token is valid
refresh_expires_in: A number in seconds describing how long the Refresh Token is valid
refresh_token: The Refresh Token as JWT
token_type: This is usually bearer

Response body example:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTTBzRmlyUUFUUE5abUE3NnZ4bkx3MHdJalJvbHBoRmZBeXlZRi14dk9nIn0.eyJleHAiOjE2MTY1OTkxODcsImlhdCI6MTYxNjU5OTEyNywianRpIjoiNzJkMDBkNjMtODY0Zi00YjRjLThlMGYtZjFjMjgxYTQ1M2UxIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLnVic3RyZWFtLmNvbS9hdXRoL3JlYWxtcy9iZWUtY3BvcyIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiI4NzFjZjAxMi0zZTdjLTQzNzItOTY3MC0yZTIwYjcyY2IxODQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJiZWUtcHVibGljLXJlc3QtYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImFhYjI1YzYxLTAxNWYtNDE1Ni1hYjJmLWY5Yjg3NzQ2ZWRlYiIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsibGlicmFyeS11c2VyIiwibGlicmFyeS1hZG1pbiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6IiIsIiRncm91cCI6WyIvbGlicmFyeS11c2VyIiwiL2dsb2JhbC9fdXNlcnMiXSwibmFtZSI6IkpvaG4gRG9lIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiZGV2ZWxvcGVyLWFwaS1kZW1vIiwiZ2l2ZW5fbmFtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkRvZSIsImVtYWlsIjoiZGV2ZWxvcGVyLWFwaS1kZW1vQHVic3RyZWFtLmNvbSJ9.Ht1rK1TzbdUGiIDtwXttDPVL0sLvMaizfeDtPpldNEBhaHP8pbTv9Bte6olYePmjXtFBuYUWRCGG9cnUucSEtWJFuJOa5mMgYMI_HCvq7SFOTnH0Z6skjwqnoCK0pF_hsMoU6MRahXduh-KFvcLKzbYY7-zVg4EmJezTT61RWPq1UajY9Hk9ZXP3T-mMla7DONrSsvu519Z3gVwqfn2-Z5iZPRWG_i7r-sRio8TZs3hkwqCTKOBL1nfuB0pK2ADiYMiHU7miHL70bmVu9nbvogBOmltbvylDgPMtr1LlobiwkWeBO4Hl-fTaZ8rX62HIb_-XgF9g1EGTp1ZkcwIzdw",
    "expires_in": 60,
    "refresh_expires_in": 86400,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmZGE2MGYxMS0yMDU4LTRmZGEtYjM3Mi0zZGZlOTc5OTVkNDUifQ.eyJleHAiOjE2MTY2ODU1MjcsImlhdCI6MTYxNjU5OTEyNywianRpIjoiZTE1YjY0MjYtZjg2Ni00MjAwLTkxYjMtNTczY2U2YzE3ZTNlIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLnVic3RyZWFtLmNvbS9hdXRoL3JlYWxtcy9iZWUtY3BvcyIsImF1ZCI6Imh0dHBzOi8vYXV0aC51YnN0cmVhbS5jb20vYXV0aC9yZWFsbXMvYmVlLWNwb3MiLCJzdWIiOiI4NzFjZjAxMi0zZTdjLTQzNzItOTY3MC0yZTIwYjcyY2IxODQiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYmVlLXB1YmxpYy1yZXN0LWFwaSIsInNlc3Npb25fc3RhdGUiOiJhYWIyNWM2MS0wMTVmLTQxNTYtYWIyZi1mOWI4Nzc0NmVkZWIiLCJzY29wZSI6IiJ9.bftAmp2MgsK9rJ1ArQ0OaNZECsD_RCO4dtQm3eYtm3g",
"token_type": "bearer"
}

If the authentication failed, the response will have a Status Code 401 (Unauthorized) and contain the following data as JSON format

{
  "$diagnoses": [
    {
      "$severity": "error",
      "$message": "Please log in to carry out this action",
      "$detail": "Response code 401 (Unauthorized) : invalid_grant: Invalid user credentials"
    }
  ]
}

Refresh token

To perform a refresh action and renew an Access Token we need to send a POST request to the refresh endpoint.

POST /api/v1/auth/refresh HTTP/1.1
Host: developer.ubstream.com
Content-Type: application/json

cURL example:

curl -X POST "https://developer.ubstream.com/api/v1/auth/refresh" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{  \"refresh_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmZGE2MGYxMS0yMDU4LTRmZGEtYjM3Mi0zZGZlOTc5OTVkNDUifQ.eyJleHAiOjE2MTY2OTQ2MjksImlhdCI6MTYxNjYwODIyOSwianRpIjoiMWRkZmE2OTMtNjI3Ni00ZWZjLTgzYTktNTFjZmU3YzgzMDc3IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLnVic3RyZWFtLmNvbS9hdXRoL3JlYWxtcy9iZWUtY3BvcyIsImF1ZCI6Imh0dHBzOi8vYXV0aC51YnN0cmVhbS5jb20vYXV0aC9yZWFsbXMvYmVlLWNwb3MiLCJzdWIiOiI4NzFjZjAxMi0zZTdjLTQzNzItOTY3MC0yZTIwYjcyY2IxODQiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYmVlLXB1YmxpYy1yZXN0LWFwaSIsInNlc3Npb25fc3RhdGUiOiJlNjBlNTY0YS1kOGZmLTQ0N2ItYjk1Ny01ZDAyM2VmYWI3NWUiLCJzY29wZSI6IiJ9.82kOSD2Fe9XbAA4CFVpGL5M0QTuLWKpiXBdIhUtz8T8\"}"

If successful, the response will have a Status Code 200 (OK) and contain the same content as the login response:

If the refresh failed, the response will have a Status Code 400 (Bad Request) and contain the following data as JSON format

{
  "$diagnoses": [
    {
      "$severity": "error",
      "$message": "We are unable to carry out the requested action, please check the settings and try again",
      "$detail": "Response code 400 (Bad Request) : invalid_grant: Invalid refresh token"
    }
  ]
}

NOTES:

Refresh Tokens are not valid indefinitely, thus Refresh Tokens will remain valid from call to call until their expiration (see refresh_expires_in), so each renewal can be performed with the same initial Refresh Token while it is valid!.
Refresh Tokens are normal Access Tokens, which can be used as Bearer Token for all Ubstream endpoints
The Access Token is valid for 1 Minute, thus a refresh is needed after 1 minute.

API keys

Into your hub, go to "Manage my account" > "Other Settings" > "API Keys"

Authentication

Login

Refresh token

API keys