What is the STREAMBOXY Public API?

The STREAMBOXY Public API is a restful API that allows you to integrate STREAMBOXY  with different Systems and automate Event & Attendee management.


When to Use the STREAMBOXY Public API?

You can leverage our Public API for automation and 3rd Party Systems integration tasks like in the following Examples:


Attendee Management:

  • Automatically Add Attenee to STREAMBOXY Event when a user bought a ticket in a Shop like Eventbrite or Xing Events user signed up for event in CRM or marketing automation systems like Salesforce Pardot, Marketo or Dynamics CRM
  • Remove Attendee once when User cancelled 
  • Add Attendees to Breakout Sessions 


Authentication:

  • Integrate 3rd Party Attendee Management Systems with Single Sign On Links


Event Management:

  • Automate Event Creation & Configuration
  • Retrieve an Publish an Event Catalog on Your Website


Analytics & Reporting:

  • Retrieve Shows / Now Shows for follow up Mailings


AddIns:

  • Interact with STREAMBOXY Data from Application Code running in AddIns. More Details in the AddIn Article.


Standards & Definitions


Payload Schema

The STREAMBOXY Public API follows the web standard for communication and accepts the JSON body format for requests and responses.


Requests Url

The STREAMBOXY Public API is available through https://api.streamboxy.com. You must use HTTPS for requests.


HTTP Request Verbs

Where possible we use the appropriate HTTP Verbs for each call to the api


HTTP Verb Description
GET Used for retrieving resources
POST Used for creating resources
PUT Used for replacing resources
PATCH Used for updating specific properties in a resource
DELETE Used for deleting resources


Common Response Codes

Where possible we try to conform to the best practices for HTTP Response Codes. The following response codes are common in STREAMBOXY Public API


HTTP Response Code Description
200 OK - Request successfull
201 CREATED - resource created successfull
202 ACCEPTED - Command Accepted
204 NO CONTENT - No content for this request
400 BAD REQUEST - Invalid syntax
401 UNAUTHORIZED - No authentication header was shown
402 PAYMENT REQUIRED - This feature needs Payment
403 FORBIDDEN - Your are not allowed to do this action
404 NOT FOUND - The requested resource could not be found
500 INTERNAL SERVER ERROR - There was an internal server error


Error Codes

Most of the API errors can be interpreted without our help. The common error response structure you are able to get is the following:

{
    "Message": "Description length should be between 1 and 500 characters.",
    "ErrorCode": "VLD0025",
    "OperationId": "<unique operation id>",
    "DetailedMessage": "Description length should be between 1 and 500 characters. The actual length was 0"
}


Here you have the following properties:

Property Name Description
Message The message of the error. This is a message which can be displayed to end-users
ErrorCode Internal Error Code
OperationId Id for the Operation. If you need further assistance you need to send us the ErrorCode and the corresponding OperationId
DetailedMessage Detailed Error Message with hints to solve this error. This message should not be displayed to end-users


Authentication


Authentication Scheme

The STREAMBOXY Public API uses the Bearer Authentication Scheme. This is an http authentication scheme that involves JWT tokens called Bearer Tokens. 

The client must send the "Authorization" header in every request to the API to be able to access protected resources. Otherwise you get an 401 error response.


Header Name Header Value
Authorization Bearer <JWT Token>


There are two types of JWT Tokens in STREAMBOXY.

  1. System Scoped - Using this Token you have full access to your tenant data. This is used for System to System interaction
  2. User Scope - With this token user access is limited to the permissions of the current user. This is used within the AddIn Model
    Currently This is supported by a few endpoints but support will be extended in the future.


System to System Authentication


Create your Client Credentials

To create a new Authentication Token you first need to log in to your STREAMBOXY Tenant and create Client Credential. 

Navigate to "Settings" -> "API Access". Here you can see the button "Create Credentials". Click this button to create new authentication credentials. 



Important: 

Save your Secret now. Due to security reasons, you will only be able to see this secret once. 


Your Client Credential set will consist of the following properties: 

  • Client Id
  • Client Secret
  • Validity 


Important:

Keep in mind that your secret will only be valid for one year after creation and need to be replaced before it expires.


Retrieve your System Scoped JWT  Token

STREAMBOXY relies on the OAuth2 client credentials grant to create system scoped JWT Tokens,


After creating your STREAMBOXY Client Credentials you can now move over the API and start making your first request to the API to receive your Bearer Token to be able to call other endpoints. For this call, you will need the following data, which can be seen at the API Access tab within the STREAMBOXY Portal: TenantId, ClientId. You will also need the stored client secret you created earlier. 

The endpoint to create your Bearer Token is: 

https://api.streamboxy.com/tenant/{your Tenant Id}/oauth/token


The following example shows an implementation of this endpoint via curl:

curl --request POST 'https://api.streamboxy.com/tenant/{your Tenant Id}/oauth/token' --header 'Content-Type: application/json' --data-raw '{ "clientId":"<Your Client Id>", "clientSecret":"<Your Client Secret>"}'


You will receive the following response: 

{"access_token":"eyJh.......","token_type":"Bearer"}


With this token, you are now able to call other endpoints in the STREAMBOXY Public API.


Important

The token is only valid for eight hours. This needs to be considered when you are using the token to make requests.
You can deal with that in the following ways:

  1. Always retrieve a new token for every request (only recommendet if you do just a few requests (i.e. less than once a minute)
  2. You parse the token expiration date (exp field in token payload) and check if the token already expired prior you do a request
  3. You use the token until you retrieve 401 errors and renew your token in the error handling routine


Don't rely on the expiration to be 8 hours and always handle expiration dynamically using the methods above. Since the expiration time might change in the future.


Rate Limiting


All public API queries are subject to limits of 300 calls per second (18000 calls per minute, 540000 calls per hour). The limits are tenant-scoped, which means that even if you're calling different endpoints with the same tenant id, the requests will add up to the same threshold value. If you've hit the limit, the next request will fail with HTTP status code 429.


Common Use Cases and Examples


Event Creation

This use case will describe the creation of an event in your tenant. For this use case, we will require you to be able to receive your authentication token. (See Authentication in this document).

The following example shows an implementation of the endpoint to create an event via curl:

curl --request POST 'https://api.streamboxy.com/tenant/{Your Tenant Id}/Session' --header 'Content-Type: application/json' --data-raw '{"title":"<Your Event Title>","description":"<Your Event description>","startDateTimeUtc":"<Your Event start time in UTC in the following format 'yyyy-MM-ddThh:mm:ssZ'>'","endDateTimeUtc":"<Your Event end time in UTC in the following format 'yyyy-MM-ddThh:mm:ssZ'>","sessionType":"Lobby","contentUrl":"<Your content url for the Lobby Event type starting with https:// >"}'


The response will contain the unique id of your created session. This id is then needed for further configuration of your session.

Example Response:

 {"id":"<unique Id of Session>"}


Participant Creation

This use case will describe the creation of a participant in your event. For this use case, we will start where we left in the use case before. We already have available the authentication token and created a session. The session id of the created session is known. Otherwise it can be retrieved through the Session Get Endpoint.

The following example shows an implementation of the endpoint to create a participant in your event via curl:

curl --request POST 'https://api.streamboxy.com/tenant/{Your Tenant Id}/Session/{Your Session Id}/SessionUser' --header 'Content-Type: application/json' --data-raw '{"role":"Participant","email":"<Email Address of the participant>","sendMailNotification": false,"name":"<Name of the Participant>","authProvider":"AccessKey"}' 


The response will contain the unique id of your created Event Participant and the Participation Link. A common integration is to have a custom registration form, which calls some logic triggering the API endpoint and then redirecting the user to this specific participation link. Another approach is to save this link in your CRM / Marketing Automation tool for individual Event Communication or SSO.

Sample Response:

{"id":"<unique Id of User>","tenantUserId":"<unique Id of user>","participantLink":"<Participation Link>", ...}


Hint: External Keys

When you integrate with other systems, you might store the ID of the Event, Session or User within STREAMBOXY.

STREAMBOXY does not check external keys for uniqeness, this is concern of your system.


External Keys can be used to reference retrieve or filter within the public API and are also available in the Backstage settings and Reports.


Here is a Sample for the External Key Field of a user:



Hint: One Time Access Key

If you want the participation link to be valid for a single entry, you can provide a property "isOneTimeAccessKey: true". That way the link gets immediately invalidated after the user entered the session. If you want to allow the user to attend the session again, you can reset the key by calling following endpoint, which will generate new key and return new participant url:

curl --request POST 'https://api.streamboxy.com/tenant/{tenantId}/Session/{sessionId}/SessionUser/{sessionUserId}/RenewParticipantLink'  --header 'Content-Type: application/json' --data-raw {} 



Hint: Custom Properties

If you need additional Data to be Stored to a User, Session or Event (i.e. Event Type, Users Company or Intrests) you can leverage STREAMBOXY Custom Properties.

You can manage custom properties and use them through the API or Backstage UI. 


You'll find more information in this Articles:



Full STREAMBOXY Public API Reference

You can find the STREAMBOXY Public API Reference inclunding all available endpoints etc. under https://api.streamboxy.com/swagger