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 event-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

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

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:

Handling Concurrency Conflicts

In order to handle Concurrency conflicts, Optimistic concurrency is implemented through property "rowVersion" in the Entity. The "rowVersion" is returned as part of the Response and during a PATCH request the payload is expected to have the latest "rowVersion". If the rowVersion is not provided or if it is not the latest then the PATCH request would fail for the Entity and an Error would be returned.

Example (EventUser PATCH)

In the snapshot above of EventUser Patch, one of the payloads is "rowVersion". If the rowVersion is not added to the request or is not the latest then the below error is returned.

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.

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"}

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>", ...}

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