API
The Gcore Customer Portal is being updated. Screenshots may not show the current version.
Streaming platform
Streaming platform
Chosen image
Home/Streaming platform/API/Real-Time Video API tutorial

Real-Time Video API tutorial

It is an easy-to-use video meeting tool.

A video conference room can be inserted in two ways:

  1. Codeless — just copy a URL, paste iframe on your page and join a call.
  2. API-based — for fine-tuning and integration with your platforms or enterprise internal systems.

Embed video meetings into an application or website with iframe or Server API/Client API allowing your team to build faster and release more often.

Get started

Create a meeting in a browser:

1. Open https://meet.gcore.com/new.

2. Click the Create conference button.

3. A Room URL will be created automatically.

4. Click the Join button.

5. Send the URL to other attendees to join your video call.

Example: https://meet.gcore.com/call/serv2testroom

Embed a video call room in your website or app via iFrame. The iframe’s src attribute is specified as the URL.

Example:

<iframe allow="camera; microphone; fullscreen; display-capture" src="https://meet.gcore.com/call/serv2testroom"></iframe>

Customize a video call room with URL attributes

Example: https://meet.gcore.com/call/serv2testroom?displayName=JohnSnow

Codeless integration

Create Room URL

1. Generate a video room ID. Use an alphanumeric character set. For example: bokxlj33.

2. Add a server location to the beginning of the set. For example, insert "serv2" for a server in the USA: serv2bokxlj33.

3. Specify /call/ as a method for your video call room.

4. Insert the Room ID into the final URL. The result should be as follows: https://meet.gcore.com/call/serv2bokxlj33

You can create a URL, save it, send it, or write it in your notes. The URL is reusable. The URL will be accessible all the time – before an event, during an event, and even 1 year later after an event.

The Room is created on a server when the first participant enters it.

The Room is automatically destroyed without saving information when the last participant leaves.

Embed Room on a Site

Embedding a meeting into a service or app requires using an iframe with the src attribute specified as the URL. Read the "Allowed domain names" section to learn how to configure your website’s domain so that browsers don’t block the iframe.

Settings of iframe must have the special permissions required for video calling:

allow="camera;microphone;fullscreen;display-capture;autoplay;screen-wake-lock"

HTTP Feature-Policy header provides a mechanism to allow: 

 

Example:

<iframe src="https://meet.gcore.com/call/serv2bokxlj33"    
allow="camera; microphone; fullscreen; display-capture; autoplay; screen-wake-lock"></iframe>

Mobile app integration

Embedding in Android app

Embedding in Android can be done in two ways:  

  1. Android Native SDK – please look at SDK and open-source demo app.
  2. WebView.

 

It’s better to use the native Android SDK. One-to-one calls and/or with many participants for real-time communication within your own app. 

There are two modules: 

  1. SDK — a  native library of video calls to be implemented into apps. The library is responsible for all internal processes: get cam/mic data, make video streams, send, and receive data to/from a video server.
  2. DEMO —  a native demo application with open-source code. The app shows cases and scenarios of SDK usage in real app. You can compile the code and run it.

   

WebView requires the use of the WebView class. To allow a video call room access the camera, you need to do two things: 

  1. Override the  WebChromeClient.onPermissionRequest  method to avoid the default implementation. You can just return true. 
  2. Add the  &nameScreenDisabled=true parameter  to the Room URL and call "Join" Client API method.

 

Embedding in iOS app

Embedding in iOS can be done in two ways:  

  1. iOS Native SDK – please look at SDK and open-source demo app
  2. WebView.

 

It’s better to use the native iOS SDK. One-to-one calls and/or with many participants for real-time communication within your own app. 

There are two modules: 

  1. SDK —  a native library of video calls to be implemented into apps. The library is responsible for all internal processes: get cam/mic data, make video streams, send, and receive data to/from a video server.  
  2. DEMO —  a native demo application with open-source code. The app shows cases and scenarios of SDK usage in real app. You can compile the code and run it.

   

WKWebView supports embedding pages that use WebRTC from iOS 14.5 onwards.  

To support older iOS versions, we recommend using one of the following options: 

  • For iOS 14.3 and 14.4, use SFSafariViewController to open a web page containing an iframe with its src specified as a video call room URL. 
  • Redirect to mobile Safari for iOS versions lower than 14.3.

 

To use Video Calls with Cordova (Phonegap) please use the plugin for SafariViewController.

Embedding in React Native app

Embedding in React Native iOS/Android can be done via wrapper:  

React Native Wrapper – please look at SDK and open-source demo app.

There are four modules: 

  1. iOS Wrapper – React Native demo app with open-source code. 
  2. Android Wrapper – React Native demo app with open-source code. 
  3. SDK – native library of video calls to be implemented into apps. The library is responsible for all internal processes: get cam/mic data, make video streams, send, and receive data to/from the video server.  
  4. DEMO – demo app with open-source code. The app shows cases and scenarios of SDK usage in the real app. You can compile the code and run it.

 

Video Call Customization

Calls or Webinars

Video call rooms

A video conferencing room is a room where all invited participants are active and have their cameras and microphones on. One video call room can hold up from 1 to 100 participants or more. 

A method to create video conferencing rooms is /call/

Example: https://meet.gcore.com/call/roomId

Webinar rooms

A webinar room is a room  where participants are divided into two groups: speakers and viewers. Speakers  are active participants with cameras and microphones. Speakers' video is shown on the screen of the webinar room, participants can watch and hear them. Viewers can only watch the speakers without interaction. They have neither camera, nor microphone on. One webinar room can hold up between 1 and 20 speakers and between 0 and 2000 viewers.   A method to create video conferencing rooms is /webinar/.  

Moreover, please see &itisparticipant attribute

Example: https://meet.gcore.com/webinar/roomId

Allowed domain names

Video calls are accessible from two types of domains:

  1. companyname.gvideo.co – example of a client's special domain in our "gvideo.co" zone. 
  2. video.domain.com – example of an external client's domain.

By default, we provide a third-level tech domain in the  "gvideo.co"  zone. If you prefer to use your own domain, please contact us.

Advanced URL Attributes for rich customization

Conferencing is customized by optional URL parameters for each iframe instance. It’s possible for each participant in a meeting to have different parameter combinations. 

&accessToken=<token> Set a one-time access token JWT, URL
&accessUrl=<url> Set your server-based authorization method for access token verification JWT, URL
&apiEvent=<url> Set webhooks server-based method for receiving server events JWT, URL
&authEvent=<header> Set specific webhooks HTTP request header for receiving server events JWT, URL
&authorizationAccess=<header> Set specific HTTP request header for access token verification JWT, URL
&autoplayWithoutAudioTrack=<true false> Set a flag "Don’t ask mic permission" on iOS devices for webinar viewer
&canRecord=<true false> Allow the recording function for a moderator
&controlsDisabled=<true false> Hide main UI controls and buttons
&disableChat=<true false> Disable text chat
&displayName=<name> Set display name of participant JWT, URL
&handEnabled=<true false> Activate the "Raising Hand" feature
&hideIndicators=<true false> Hide icons in a participant's tile (mic, cam, name, etc.)
&itisparticipant=<true false> Set a role of a viewer or a participant in webinars
&lang=<code> Set the interface language explicitly URL
&maxBroadcasters=<num> Set the maximum number of participants with camera/audio devices JWT,URL
&maxWatchers=<num> Set the maximum number of viewers without camera/audio devices JWT, URL
&minimizeTiles=<true false> Increase the number of participants displayed on a single screen without scrolling to the maximum
&nameScreenDisabled=<true false> Skip welcome page with a cam/mic selection and a name input
&peerId=<id> ID of a participant from your internal system JWT, URL
&role=<role> Set a privilege role for a participant JWT only
&sortPeers=<true false> Move participants with cameras up to the visible area
&startWithFS=<true false> Start meeting in the full screen mode
&token=<jwt> Set a JWT token JWT, URL
&video=<url> Display an external HTML player with external video broadcasting for joint viewing JWT, URL
&waitingRoom=<true false> Activate waiting room
Examples:

1. https://meet.gcore.com/call/serv2testroom?displayName=JohnSnow
  
2. https://meet.gcore.com/call/serv2testroom?displayName=JohnSnow&disableChat=true
  
3. https://meet.gcore.com/call/serv2testroom?displayName=JohnSnow&disableChat=true&lang=en

Attribute details

&accessToken=<token>

It is a security access token generated on your side. If this parameter is specified, then, whenever a user enters a room, our server will additionally ask your authorization server whether the user with the peerID and accessToken parameters is allowed to connect. For more details, refer to the server-side authorization method. 

Type: String. default = not set.

Example: &accessToken=802380f4-dd70-4d60-9738-fb5ae8709ae7

&autoplayWithoutAudioTrack=<true|false>

It is used only for iOS devices and only for webinars.  

The iOS Safari Browser policy requires microphone permission to use audio with WebRTC. So, the browser requests a passive viewer (with no cam/mic buttons) in a webinar room to allow access to the mic. This parameter ensures the browser will not ask for access to a microphone, but will play audio using the simple "play" method. 

Type: Boolean, default = false.

Example: &autoplayWithoutAudioTrack=true

&canRecord=<true|false>

This allows to record and save everything what happens in a room to the Cloud. Not everyone needs a recording for security reasons, legal restrictions, or storage usage. Recording feature can be activated with this attribute. If the feature is on, a moderator can turn on the recording using the UI button.

Type: Boolean, default = false.

Example: &canRecord=true

&controlsDisabled=<true|false>

It is used to hide general controls and buttons from the screen. In this case, you should use ClientAPI methods to manage actions and allow users to turn on/off their cams/mics.

Type: Boolean, default = false.

Example: &controlsDisabled=true

&disableChat=<true|false>

This is designed to disable the chat function. If you add the parameter, the "Chat" button will be un-clickable and chatting will be unavailable for participants. It is useful when you prefer to use our own chat.

Type=Boolean, default value = false.

Example: &disbleChat=true

&handEnabled=<true|false>

This parameter helps to activate the "Raise Hand" feature in a room. Participants will be able to click the "Raise hand" button, and the raised hand icon will appear. The icon is displayed in participant’s tile and in the list of participants in the moderator’s panel.  

Type=Boolean, default value = false. 

Example: &handEnabled=true 

&hideIndicators=<true|false>

It is used to make icons inside a tile of a participant invisible. With this parameter, you can hide a participant name and the following icons: cam on/off, mic on/off, absence, raised hand, and pin button.

Type=Boolean, default value = false.

Example: &hideIndicators=true

&displayName=<name>

This allows to display a name of a participant.

A participant’s name may be known before they join the meeting. It is possible to pass their name from your internal system, so the user doesn't have to enter it on the welcome page.

If you specify the name in the attribute, the user will not be able to change it through UI.

Type: String, default value = not set.

Example: &displayName=JohnSnow

&itisparticipant=<true|false>

This parameter determines roles in a webinar room where there are participants and viewers. All attendees are viewers only by default.

Participants join a room as regular users and can turn on their camera and microphone. Participants also have a standard rectangle icon of a participant. Viewers can observe what is happening in a room, can see and hear, but they do not have a dedicated participant rectangle icon and cannot turn on their camera or microphone.

Note: It is used for webinar rooms only.

Type = Boolean, default value = false.

Example: &itisparticipant=true

&lang=<code>

This helps to set the UI language of a meeting to match your product or service. In general, the UI language depends on language settings of a participant's browser. A user sets the language in their browser settings, and then its value is transmitted by the browser in the "Accept-Language" header of an HTTP request info.  

Select one of these: 

  • English = en
  • French = fr 
  • German = de 
  • Luxembourgian = lb

 

Therefore, in most cases, you do not need to specify this parameter explicitly. If the UI of a video room  is translated and available for user’s language, then UI will be automatically switched to it. If a language is unavailable, the default English version will be shown. 

But sometimes you need to explicitly set a language based on your internal/enterprise settings, use this parameter. 

Type: String, default = not set.

Example: &lang=en

&maxBroadcasters=<num>

This sets the number of concurrent active attendees in a room at one time. This is the maximum value of users/attendees with turned on cams/mics.  

If another user starts to speak (be active, turn on the cam/mic), but the number of active attendees exceeds the specified value, then this user will receive a system error that they cannot turn it on: "The limit of maximum active attendees is exceeded". 

If no value is specified in the URL, any participant can turn on cam/mic. Please be aware that the number of active users is directly proportional to the load on media servers. With an overwhelming number of active attendees, a server may become overloaded, and newly connected users may see a connection error. 

The maxBroadcasters and maxWatchers parameters should be specified for each participant in the URL. Please refer to &maxWatchers parameter. 

Type: Numeric, default = 0. 

Example: &maxBroadcasters=10

&maxWatchers=<num>

This sets the number of concurrent attendees in a room at one time. This is the maximum value of users/viewers that can be in a room and be represented by their own "participant" rectangle. Participants can turn on their cam/mic at any time.   

The maxBroadcasters and maxWatchers parameters should be specified for each participant in the URL. Please refer to &maxWatchers parameter. 

Type: Numeric, default = 0. 

Example: &maxWatchers=50 

&minimizeTiles=<true|false>

This helps to squeeze the participants' tiles so that as many participants as possible can fit into one view without scrolling. This parameter allows increasing the number of simultaneously displayed tiles of participants on a screen to the maximum.

Type: Boolean, default = false.

Example: &minimizeTiles=true

&nameScreenDisabled=<true|false>

This helps to skip the welcome page with the name input field and cam/mic selection. You can skip the cam/mic selection elements when you already know the user's devices, or you need to connect the user immediately.

In that case, you should specify a user’s name in the attribute and use ClientAPI for "Join" method. Please refer to the "Join" method.

Type: Boolean, default = false.

Example: &nameScreenDisabled=true

&peerId=<id>

This is an identifier of a participant in case you want to set it explicitly. It is used for synchronization with your database or enterprise services.

You can select any value you prefer: number, GUID or even email.

Please, note: Only one session is possible with one unique identifier. If another participant with the same peerID connects, a new session will be created for the recent participant, while the session of the first one will be terminated. This is also the case when a link is opened in a different browser: a new session will be created with the recent browser, while previous connection will be terminated.

Example:

  • User1 opens a link with &peerID=5 and then User2 opens the same link with &peerID=5. The second user will log in, but the server connection with the first user will be closed and the User1 will not be able to participate. Thus, you need to use two different peerID's.
  • A User opens a link with &peerID=5 on a desktop computer and then opens the same link on a mobile device. They will log in on the mobile device, but the server connection with the desktop computer will be closed.

The peerID is used for:

  • ClientAPI methods when you want to apply a method for a specific user.
  • Download statistics on the attendance of a video call room and the duration of the users' presence on a call.

Type = String, default value = set by the video server with a random GUID value.

Example: &peerId=802380f4-dd70-4d60-9738-fb5ae8709ae7

&role=<role>

This parameter sets a privileged role for a participant.

Values:

  • [not set] — regular participant.
  • moderator —  super-user who can manage participants and video call settings.
  • interpreter —  (beta) special role for interpreters from one language to another. A special audio channel is dedicated for them. Be aware that users of this role cannot turn on their cameras.

 

By default, all attendees are regular participants. They can manage their own cams and mics. But a moderator can manage participants, turn off their cams/mics, allow entering, etc. You can assign the "moderator" role to a host, and all other attendees will be regular participants. For more details, please refer to the Moderator feature.

Type: String, default = not set.

Example: &role=moderator

&sortPeers=<true|false>

It is used to arrange tiles of participants so that those who have cameras on will be displayed on the top.  

By default, the participants' tiles are ordered based on the time they connected. This order does not change during a meeting. For example, if first users connect without video, and then the last participant turns on the camera, they may be placed under the scrolling (visible area) of the screen and no one will see them. 

Using this parameter allows you to show active participants with video. However, enabling this option increases load on participants' CPUs. 

Type=Boolean, default value = false.

Example: &sortPeers=true

&startWithFS=<true|false>

It helps to start a meeting room in the Full Screen mode. Please see the "Full Screen mode" in our Knowledge Base.

Type: Boolean, default = false.

Example: &startWithFS=true

&token=<jwt>

The JSON Web Tokens is an open, standard method for representing claims securely between two parties: https://jwt.io/

The JWT allows you:

  • To specify attributes inside a token, rather than URL attributes.
  • Sign a token with a secret key and be sure that all parameters in it are specified by you, and cannot be changed by someone else.

Please see "Security" for details.

Type=String, default value = not set.

Example:

&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X6GFjopXf62C6y4OgeeEk9KEb1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zWMk3sYLpWxULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg

&tokenLifetime=<milliseconds>

The parameter limits the lifetime of a token. The lifetime is counted in milliseconds from the first connection. After the specified period has expired, a participant cannot reconnect to the room with the token.

Type=Number, default value = not set.

Example: &tokenLifetime=60000

&video=<url>

This is a super feature for joint viewing of online broadcasts directly in a video call room. No, you do not need to "share screen" with others and lose both video and audio quality and overload one of the participant's PC. You just need to insert a code of the YouTube player, our player, or any other HTML player, and it will appear for all participants in the room. Besides, the player saves all its standard functions: adaptive bitrate, counting unique viewers, displaying ads, Google Analytics counter, etc. Please refer to .

Type=String, default value = not set.

Example: https://meet.gcore.com/call/serv2testroom?displayName=John%20Snow&video=https%3A%2F%2Fwww.youtube.com%2Fembed%2FXBPjVzSoepo

&waitingRoom=<true|false>

The waiting room function allows a moderator to manually determine which user is allowed to enter a video call room and who is not.

After enabling the feature, each participant will see the "Please wait for confirmation" message.

Type: Boolean, default = false.

Example: &waitingRoom=true

Debug and Dev URL attributes only

A set of debug attributes can be used by developers to create and test a video call room.

These parameters are used for debugging only.

&accessUrl=<url>

A URL of REST method to check accessToken. Please see "Authentication of participants" for details. 

Make sure you use https:// instead of http://

Please do not use this attribute publicly. For public use, a URL must be registered on our server or in your account. 

Type=String, default value = not set.

Example: &accessUrl= https://your.domain.com/api/gcore/auth

&apiEvent=<url>

A URL to get webhooks/events from a video calls server. Please see "Webhooks" for details.

Make sure you use https:// instead of http://.

Please do not use this attribute publicly. For public use, URL must be registered on our server or in your account.

Type=String, default value = not set.

Example: &apiEvent=https://your.domain.com/api/gcore/webhook

&authEvent=<header>

This is for extra header request parameters and credentials for server-side webhooks/events. Use it for enabling Basic or Bearer authentication, etc.

Please do not use this attribute publicly. For public use, a URL must be registered on our server or in your account.

Type=String, default value = not set.

Example: &authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D

&authorizationAccess=<header>

This is for extra header request parameters and credentials for server-side check of authorization.

Use it for enabling Basic or Bearer authentication, etc.

Please do not use this attribute publicly. For public use, URL must be registered on our server or in your account.

Type=String, default value = not set.

Example: &authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D

Moderator

By default, all attendees are regular participants. They can manage their own cams and mics. But a moderator can manage participants, turn off their cams/mics, allow entering etc. 

A moderator can do the following:  

1. Operate the "Waiting room" function:  

  • Activate and deactivate a waiting room.
  • Confirm and reject a participant's entry

2. Operate cameras and microphones of participants: 

  • Allow or disallow cameras and microphones.
  • Ask participants to turn on cameras and microphones.

3. Operate the sharing screen feature:

  • Allow or disallow the screen sharing.
  • Ask to turn on the screen sharing.

4. Operate raised hands: 

  • Remove a participant's hand.

5. Operate the list of participants: 

  • Kick the user out of the room.

 

To use the moderator role, you need to follow these steps: 

  1. Get a Secret Key for JWT. See the "Security" section.  
  2. Generate a link for regular participants with call/roomId parameter. 
  3. Generate a JWT token and add additional attribute &role=moderator to it.  
  4. Generate a link for moderators. Concatenate the JWT token from Step 3 to the general link from Step 2.

 

Example:

Link for a regular user:

https://meet.gcore.com/call/serv0_test1

Link for a moderator:

https://meet.gcore.com/call/serv0_test1?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwid2FpdGluZ1Jvb20iOnRydWUsImhhbmRFbmFibGVkIjp0cnVlfQ.DO_JHMDfK2mi5rycIepLVxDVs0qcQAXAhHvI7hcOIjw

Where JWT is:

  • HEADER: (ALGORITHM & TOKEN TYPE)
  • { "alg": "HS256", "typ": "JWT" }
  • PAYLOAD: (DATA)
  • { "role": "moderator", "waitingRoom": true, "handEnabled": true, "roomId": "serv0_test1" }

Recording

What can be recorded

Recording is a video recording of the entire interface of a meeting room, as it is seen by regular viewers. A video includes:  

  • attendees,  
  • screen sharing, 
  • original audio of speakers.

  

Recording is a complex process that is carried out by our professional Streaming Platform. The video is recorded on a cloud server and is also stored in the Cloud of the Streaming Platform.   

When a meeting is over and a video is recorded, it is automatically converted and becomes available for viewing in the video player. You can download the video, copy the player code for viewing on a web site, or get HLS video stream and insert manifest.m3u8 into your mobile app. 

Recording can be started by moderator only. 

To record, you need to follow these steps: 

1. Generate a JWT token with additional attribute role=moderator inside it.  2. Add attribute canRecord=_true into the JWT.  3. Open a room with the link.   4. Open the "Moderator" panel inside a room.   5. Press the "Record" button.   6. Press the "Stop" button. 

A JWT example: 

PAYLOAD: (DATA) 

{ "role": "moderator", "canRecord": true, "roomId": "serv0_test1" } 

Auto-recording

By default, a moderator can manually record meetings.  

If you want to record all meeting rooms automatically, you can enable the "Auto Recording" feature for your account.  

  • Recording starts automatically for every new room in ±60 seconds after the first user logs in. 
  • Recording goes on for as long as there is at least one user in the room. 
  • Recording stops automatically after ±60 seconds after last user logs out. Thus, if by chance all users leave the room and return without a timeout, then the recording will continue.

 

Please note that, if one of the users forgets to close a browser tab, they still will be present in the room. And if they are present in the room, recording will continue. 

Ask your manager or support team to enable the Auto recording feature. 

Where to find recorded videos

Recording of room is made by our Streaming Platform. Video files are stored in the media storage. 

Steps to find a video: 

  1. Open your personal dashboard via link: https://streaming.gcore.com/.  
  2. Select the "Video hosting" tab. 
  3. Select videos with the "Recording" title with the exact roomId and the exact time.  
  4. Open the video.  
  5. Copy the video player code, link of the player, or download the video on the "export" tab.

 

Also, you can use Special API of the Streaming Platform. Please see the "Getting Recorded Video" section. 

How to set up our recording feature

As you know, recording of a room is made by our Streaming Platform, and video files are stored in the media storage. 

Steps: 

  1. Generate a permanent token in your personal account via the link.  
  2. Use parameters:

 

  • Name = "Video conference recording" or any title you prefer; 
  • Role = Administrator; 
  • Expiration = Never expire.

  3. Copy the token from the result page  4. Send us the copied token  5. Add the &canRecord advanced attribute to the URL for a moderator, or ask us to set the Auto Recording feature.

Example of a permanent token:

1030$0b219f0239c7a418c499a9b0f4d93f0b081700000c346ad254694b15d09981d7cf6b24e41a243df6e9e23d5483820d98921d64c0cb06e9981c842ab31fd0e4db 

Language Interpretation (beta)

In normal use, each user hears the original audio of a speaker. The interpretation feature allows users to hear the interpreter’s speech, that they can understand, in simultaneous translation mode. 

If a moderator wants to include interpreters in their meetings or webinars, they now can enable Language Interpretation. With it, a host can designate an unlimited number (over 20) of participants as interpreters during a video session.  

When a meeting or webinar starts, a host can turn on the interpretation feature which will provide interpreters with their own audio channels for the language they translate to. Attendees can then select the channel and listen to the audio translated in the language they need. They can also mute the original audio so not to hear it at a lower volume together with their chosen language.    

In case of meetings with interpretation, only the original audio of a meeting or webinar is recorded, not the translated speech.  

The languages below are available by default. If you need more, just please let us know: 

  • Chinese, zh 
  • Dutch, nl 
  • English, en 
  • French, fr 
  • German, de 
  • Luxembourgian, lb 
  • Portuguese, pt
  • Spanish, es 
  • Swedish, sv 
  • Ukrainian, uk

 

There can be more than one interpreter for one language. If several interpreters use the same link, all of them can speak in the corresponding channel. They can speak both simultaneously or/and consecutively. For consecutive interpretation, they just need to mute the microphones. 

For regular attendees, new language automatically appears when an interpreter is connected. 

If an interpreter disconnects from a room for whatever reason, regular users can select the language for 30 seconds. If none of the interpreters reconnects, the language will become unavailable for select, and listeners of that language will be switched to the original audio.   

A JWT example is: 

  • PAYLOAD: (DATA) 
  • { "role": "interpreter", "featureInterpreters": true, "intLang": "de", "roomId": "serv0_test1" }

 

example of the video module API integration

Client API

Iframe Integration

Example of iFrame integration

<iframe allow="camera; microphone; display-capture" style="height: 100%; width: 100%;" src="https://meet.gcore.com/webinar/qwesfder4w4?displayName=Tom&accessToken=sda3-q23aed-aerae&peerId=123123-321as-waaew-ads&apiEvent=https://example.com/api/meet&accessUrl=https://example.com/api/accessCheck/&itisparticipant=true&nameScreenDisabled=true&startWithFS=true&controlsDisabled=true"></iframe>

Please see Embed a Room on Site and Attributes details.

Interaction with iFrame

There is a special library for interacting with iframe, which should be loaded separately.

<script type="text/javascript" charset="utf-8" src="https://<yourdomain.gvideo.co>/meetBridgeApi.js"></script> 

Example:

<script type="text/javascript" charset="utf-8" src="https://meet.gcore.com/meetBridgeApi.js"></script> 

JavaScript's method for initialization:

meetIframeBridge = new MeetIframeBridge.default({ element: $iframe.get(0), roomId: "serv1m6oci9e8" });

Where:

  • element is a DOM object of iFrame.
  • roomIdis an ID of the room.

Note: Before initializing a class, you need to wait for an iframe element to be loaded.

Public methods of Real-Time Video iframe

Client API methods allow you to control a video room, perform actions with hidden main controls, react to what is happening in a room.

Example of method:

Initializing:

var meetIframeBridge;  
$('#meetframe').on("load", function() { 
            meetIframeBridge = new MeetIframeBridge.default({ element: $("#meetframe")[0], roomId: "serv1m6oci9e8" });       
});

Joining:

meetIframeBridge.method({ name: "join", data: {constraints: {video: false, audio: false }}, callback: (e) => { alert(1); return true; } });

Volume adjusting:

meetIframeBridge.method({ name: "setVolume", data: 100, callback: (e) => { alert(1); return true; } });

Name changing:

meetIframeBridge.method({ name: "changeDisplayName", data: "Tom", callback: (e) => { // return value } });

Getting screenshot of a user’s video:

meetIframeBridge.method({ name: "getScreenshotByPeerId", data: "id", callback: (e) => { // "e" parameter will have screenshotted data } });
Method name Parameters Description
join "constraints" = object

Setup new devices:
data: {constraints: { video: { deviceId: 'id', label: 'label', groupId: 'groupId', kind: 'video'}, audio: { deviceId: 'deviceId', label: 'label', groupId: 'groupId', kind: 'audio'}}}

If you want to use devices by default:
data: {constraints: {video: true, audio: true }}
The Join method receives a stream from these devices (usually used with the nameScreenDisabled parameter)
enableMic Unmute a microphone
disableMic Mute a microphone
enableWebcam Turn on a camera
disableWebcam Turn off a camera
enableShare Enable the screen sharing
disableShare Disable the screen sharing
changeDisplayName "name"
data: string
Change a name
setVolume "volume"
data: number
Set a volume level (0 - 100)
getScreenshotByPeerId "peerId"
data: string
Get a screenshot of a user with an id equal to peerId, the screenshot is given in base64
setControlsVisible "visible"
data: bool
Show and hide controls
isCameraEnabled The user's camera is enabled
isMicroEnabled The user's microphone is enabled
isShareEnabled The user's sharing is enabled
changeDevice "constraints" = object
data: {constraints: { audio: { deviceId: 'deviceId', label: 'label', groupId: 'groupId', kind: 'audio'}}}

or

data: {constraints: { video: { deviceId: 'id', label: 'label', groupId: 'groupId', kind: 'video'}}}
Change a device on the fly. Specify 1 (one) device per method call.
playAudio Start audio that failed to play (usually used together with autoplayWithoutAudioTrack)
muteAudio Mute incoming audio
unmuteAudio Unmute incoming audio
setBitrate "bitrateValue"
data: number
Set the maximum video bitrate in a room
isFullscreenEnabled The fullscreen is enabled
enableFullscreen Enable the fullscreen
disableFullscreen Disable the fullscreen
enablePin "peerId"
data: string
Enable the PIN for a specified user
disablePin Disable the PIN
setLocale "locale"
data: string
Dynamic language changes, available languages: en, ru
disabledTrackByModerator "peerId", "kind = (audio || video)"
data: {userPeerId: 'peerId', kind: 'audio'}
Turn off video or audio from another user in a moderator mode. Only a moderator can disable video and audio
disableAllMics Mute mics of all participants. It can be used only by a moderator
disableAllCameras Turn off cams of all participants. It can be used only by a moderator
setHideIndicators "hide"
data: bool
Show and hide indicators of other users (icons for microphones, cameras, username, pin button)

Events from an iframe

Events on the client side allow you to react quickly to actions in a video room.

Example of event subscription:

meetIframeBridge.on('switchOnCamera', (e) => { your code here });
Event name Data Description
join peerId, displayName A user is added to the room.
ready Iframe is fully loaded and ready to go.
readyToJoin The Room is ready to "join".
switchOnCamera peerId, displayName Camera is on
switchOffCamera peerId, displayName Camera is off
nerrorGetCamera peerId, displayName Camera connection error
switchOnMic peerId, displayName Microphone is on
switchOffMic peerId, displayName Microphone off
errorGetMic peerId, displayName Microphone connection error
switchOnShare peerId, displayName Screen sharing enabled
switchOffShare peerId, displayName Screen sharing is off
errorGetShare peerId, displayName Screen sharing error
newPeer peerId, displayName New user connected
peerClosed peerId, displayName The user left the room
connectionFailed Connection to the server failed
disconnected Connection to the server was closed (example: the server is unavailable)
connectionClosed The user has closed the connection to the server
connectionError peerId, error message An error message appeared on a client's side or on a server's side
playingAudioPrevent Audio doesn't play unless clicking (used together with the autoplayWithoutAudioTrack parameter)
switchOnPin peerId The PIN function is on
switchOffPin The PIN function is off
errorGetPin peerId The PIN feature error

Server API

Server Endpoints

Video Conferencing Endpoints

Please see REST API specification. Below is a brief list of endpoints.

To access Server API methods, you need to be authenticated. Please see "Server API Authentication" below.

Method name Parameters Description
/rooms/:roomId/closePeer peerId,
body:{peerId: id}
Remove a user from a room, POST
/rooms/:roomId/closeRoom Delete a room, GET
/rooms/:roomId/durationOfBroadcast View how long the room existed, GET
/rooms/:roomId/exists Check if the specified room exists, GET
/rooms/:roomId/existingPeer
(depricated)
peerId,
body:{peerId: id}
Check does the user exist in the room, POST

Please, use new method instead – /rooms/:roomId/existingPeer/:peerId
/rooms/:roomId/existingPeer/:peerId Check does the user exist in the room, GET
/rooms/:roomId/numberPeers View the number of participants in the room, GET
chat/clear-rooms body: { hostname: string, rooms: [{roomId: id, type: "call"|"webinar"}]} Clear chat history in specific rooms, POST

Where:
"hostname" – domain name
"type" – type of room, unnecessary attribute, where "call" is default value
/rooms/:roomId/recording/start Start recording for a specific room, POST
/rooms/:roomId/recording/stop Stop recording for a specific room, POST
/rooms/:roomId/recording Check video recording status, GET

Example #1:

curl -L -X GET 'https://webrtc3.gvideo.co/rooms/serv1l8bsg8zw/durationOfBroadcast' -H 'Authorization: Bearer eyJ0eXAiOiJKV'

Example #2:

curl -X POST 'https://webrtc3.gvideo.co/rooms/serv0dxrpxoqr/recording/start' -H 'Authorization: Bearer eyJ0eXAiOiJKV'

Example #3:

Request:

curl -L -X POST 'https://webrtc3.gvideo.co/chat/clear-rooms' \  
-H 'Authorization: Bearer eyJ0eXAiOiJKV' \  
-H 'Content-Type: application/json' \  
--data-raw '{  
   "hostname": "102748.gvideo.co",  
   "rooms": [  
    {  
      "roomId": "serv0d17nfe1s"  
    }  
  ]  
}'

Response: 200 OK {"deleted":["serv0d17nfe1s"]} 

Common Response Codes

There is a list of common response codes of REST API methods:

Code Response Label Description
200 OK OK
400 Bad Request Token, roomId, peerId not found
401 Unauthorized Invalid token
403 Forbidden Access denied, contact your administrator
404 Not found Invalid room ID
500 Internal Server Error Server connection error

List of servers

We have a lot of servers worldwide. Some of them are for public usage.

A server can be derived from a room ID. For example: &roomId = serv1qweqwe.

Server Country Server URL Description
serv0 Luxembourg https://webrtc3.gvideo.co:443 DEFAULT server, unless states otherwise
serv1 Australia https://webrtc4.gvideo.co:443
serv2 USA https://webrtc5.gvideo.co:443
serv3 Singapore https://webrtc6.gvideo.co:443

Note: There is an offset in a server’s URL. This is a temporary but necessary solution that will be changed soon. We will inform you additionally.

For debug purposes, you can call a server endpoint directly. But for public use, we apply strong restrictions and increase the level of security. Please tell us if you want to allow server-calls for specific servers and security parameters. In this case, all other calls will be rejected.

Example of  video server performance check

A call method such as:

https://webrtc3.gvideo.co/rooms/serv0l8bsg8zw1/durationOfBroadcast

For a non-existent room, the answer will be 400 error. If it is a 500 error or a timeout error, the server is unavailable.

Webhooks

Webhooks are user-defined callbacks triggered by meeting events. Webhooks are pushed to the URL specified in the apiEvent attribute:

Event name Parameters Description
joinPeer roomId, peerId, displayName New user connected
closePeer roomId, peerId, displayName User disconnected

Webhook joinPeer

This is a method of notifying that a participant has joined a room. This method is used for extra authentication on your side.

POST /joinPeer

Attributes:

  • roomId
  • peerId
  • displayName

Example: 

{"event":"connected","roomId":"44fde071","peerId":"de9b6927","displayName":"user16"}

Example:

https://meet.gcore.com/call/44fde071?displayName=user16&accessToken=caa630bb&peerId=de9b6927&apiEvent=https://dev.com/api/events&accessUrl=https://dev.com/api/accesscheck

Webhook closePeer

This is a method of notifying that the connection between a server and a participant’s browser has been closed. In most cases, this means that the participant has left the room intentionally or due to a connection issue.

POST /closePeer

Attributes:

  • roomId
  • peerId
  • displayName

Example:

{"event":"disconnected","roomId":"44fde071","peerId":"de9b6927","displayName":"user16"}

Special API of Streaming Platform

Video conferencing tool manages data in real time. Thus, Server API and Client API of video conferencing are designed to control the behavior of users and video rooms in real time.

Statistics on usage and video recordings are stored in the Streaming Platform. Thus, please use

Video Platform’s REST API for those methods: https://api.gcore.com/docs/streaming.

To access Video Platform API, you need to be authenticated. Please see "Authentication of Participants and Access Limitation" above.

Statistics

Video conferencing tool sends statistics data every 30 seconds to the Video Platform servers. This means that the usage statistics can always be multiply by 30 seconds. 

  1. General data about a room:

This is a summary about a room.

GET /streaming/statistics/peers/summary

Attributes:

  • room_id
  • from – start period of selecting data
  • to – finish period of selecting data

Output codes: 

  • 200 – OK, json object with the data. 
  • 400 – Bad Request, in case of incorrect input attribute values. 
  • 403 – Unauthorized access.   
  • 404 – Not found, in case there is no data for a room or room is not found in statistics. 
  • 500 – Internal error.

 

Output values:

  • participants – total sum of unique participants in a room.
  • start_time – UNIX time in seconds when the first participant entered, ex = 1624276920.
  • end_time – UNIX time in seconds when the last participant left, ex = 1624358940
  • duration – number of seconds when the room was «active», calculated as difference from the end_time parameter value and the start_time parameter value. Ex = 90660

Note: The result is aggregated data for all sessions of the specified room between «from» period until «to» period. Thus, if you use the same room ID each day, then use separate periods.

Example:

https://meet.gcore.com/call/serv2test1 used for 60 minutes each day on Monday Jun 21 and on Tuesday Jun 22.

  • /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-21T23:59:59.99Z&room_id=serv1test1 – will return 60 minutes (60 mins on Jun 21).
  • /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test1 – will return 120 minutes (60 mins on Jun 21 + 60 mins on Jun 22).

Example of usage:

https://api.gcore.com/streaming/statistics/peers/summary/?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv2test2a

Example of return data:

{   
    "data": {   
        "participants": 3,   
        "start_time": 1624268280,   
        "end_time": 1624358940,   
        "duration": 90660   
    },   
    "errors": []  
}
  1. Detailed data per participant:

This is data for each participant’s sessions in a room.

If an event lasted 60 minutes, and the user attended it for the first 5 minutes, then left the room, and joined again for the last 5 minutes, the statistics will reflect two sessions, each lasted for five minutes: 5 min + 5 min = 10 minutes (that is, = 600 seconds, instead of 3600 seconds of the total duration).

GET /streaming/statistics/peers/

Attributes:

  • room_id
  • from
  • to

Output codes:

  • 200 – OK, json object with the data.
  • 400 – Bad Request, in case of incorrect input attribute values.
  • 403 – Unauthorized access.
  • 404 – Not found, in case there is no data for room or room is not found in statistics.
  • 500 – Internal error.

Output values:

  • array of participant sessions
  • person_id – peerId data (your value, if it was specified in URL attributes, or unique GUID made automatically if it was omitted)
  • join_time – UNIX time in seconds of the participant's join time, ex = 1624268280
  • leave_time – UNIX time in seconds of the participant's leave time, ex = 1624269300
  • duration – number of seconds of the session, ex = 1260

Example of usage:

https://api.gcore.com/streaming/statistics/peers/summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv2test2a

Example of return data:

{   
    "data": [   
        {   
            "person_id": "peer2",   
            "join_time": 1624268640,   
            "leave_time": 1624269300,   
            "duration": 660   
        },   
        {   
            "person_id": "peer1",   
            "join_time": 1624270800,   
            "leave_time": 1624274520,   
            "duration": 3720   
        },   
        {   
            "person_id": "peer1",   
            "join_time": 1624270380,   
            "leave_time": 1624270740,   
            "duration": 360   
        }   
    ],   
    "errors": []   
} 

Getting Recorded Video

Recordings of room meetings are stored in the media storage of the Streaming Platform.

You need to search the video and then get by id.

  1. Search a video
GET /streaming/videos/search

Attributes: q – Search query. The search performed among all video names. Specify roomId as a search query.

Output values: Array of available videos for specified ID.

If a session lasted more than 4 hours, the recording will be divided into several videos for 4 hours each. In this case, you need to get all videos separately.

Please see more details in documentation

  1. Get video metadata

 

GET https://api.gcore.com/streaming/videos/{video_id}

Please see more details in documentation.  

Output values: Metadata of the video. Use fields "hls_url" for .m3u8 stream in external players or "origin_host"+"origin_resource" for getting an original MP4 file.  

Example of output data:  

{   
  "hls_url": "https://id10835.gcore.com/videos/10835_UaX2pjxen2guUw3/master.m3u8",   
  "origin_host": "s-ed1.cloud.gcore.lu",   
  "origin_resource": "9208-mediaplatform10835/videos/UaX2pjxen2guUw3.mp4",   
}

Please see more details in documentation.  

Example of usage: 

Step 1: https://api.gcore.com/streaming/videos/search?q=serv1test2a

Step 2: https://api.gcore.com/streaming/videos/117800

Rate Limits

There is a general limit of four requests per second. If you exceed the rate limit, you will receive a message.

Security

Calling API should be done through an endpoint on your server. This will help to avoid exposing secret keys to users and to keep them safe.

Validating Client API Requests

What is a JWT

To access Client API, we use  JSON Web Tokens (JWT), which is an open, industry standard  RFC 7519  method for representing claims securely between two parties.

For more information what JWT is and how to use it please visit https://jwt.io/introduction

JWT allows you to accurately determine the validity of the video room settings and unambiguously determine the belonging of the token to your account. 

To use the JWT, you need a Public & Secret Key. A new key is generated by you. Send us your public part of the key via support or personal manager. Please see "RSA Public & Secret Key generation" section below for details.

Limitations when using JWT

You can activate the option to use the JWT in your account. If you activate it, you will have to send a JWT &token=xxx in every request. Without a token, the "Access denied" message will appear.

If you activate the JWT option, you will not be able to use the &accessToken=xxx attribute.

JWT Header

The header typically consists of two parts: the type of the token and the signing algorithm being used.

Signing algorithms are:

  • RS256 – asymmetric key,
  • HS256 – symmetric key.
HEADER:ALGORITHM & TOKEN TYPE   
{  
"typ": "JWT",  
"alg": "RS256"  
}
HEADER:ALGORITHM & TOKEN TYPE   
{  
"typ": "JWT",  
"alg": "HS256"  
}

JWT Body

The body of a JWT contains important data that should be signed and verified. The data in a JWT has a higher priority over the values of the same parameters specified in the URL attributes. This means that if an attribute value is specified both in a JWT and in the URL attribute set, the value from the JWT will be used.

Please refer to the table of attributes above to see the parameters that can be set in a JWT.

Priority of data from a JWT and URL:

  • Parameters with the "JWT" label can be specified inside a token or as an attribute in the URL. If an attribute value is specified in a token, the value in the URL is ignored. If an attribute is not specified in a token, the attribute value will be taken from the URL.
  • Parameters with the "URL" label can only be specified as an attribute in the URL.

The list of extra attributes for a JWT: 

  • startTime – planned start time of an event in a video room. Please see "Webhook joinPeer method". Date/time is in UTC time zone only, represented as number (milliseconds since Unix epoch), formatted as ISO 8601.
  • iat – (optional) Issued At. The "iat" claim identifies the time at which the JWT was issued. This claim can be used to determine the age of a JWT. Date/time is in UTC time zone only, representedas number (milliseconds since Unix epoch), formatted as ISO 8601.

The list of attributes is expanding, tell us what attributes (from general list of URL attributes) you need inside a token.

PAYLOAD:DATA  
{  
"roomId": "abcd1234",  
"role": "moderator",  
"startTime": "2022-06-21T00:00:00.0Z",  
"iat": 1516239022  
}

Example:

https://meet.gcore.com/call/YOUR_ROOM_ID?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X_6GFjopXf62C6y4OgeeEk9KEb_1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zW_Mk3sYLpW_xULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg

JWT Signature

Use your key to sign the token with the algorithm specified in the header.

The signature is used to verify the data wasn't changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

We highly recommend using RS256 asymmetric type of algorithm. See section "RSA Public & Secret Key generation" to generate public/private keys.

Validating Server API Requests

Validation with Authorization Header

To access Server API and Streaming Platform API, we use an API token in the Authorization header. The API token is a unique key that all users and applications should add to requests to interact with our services.

Please authenticate via API.

Choose one of the methods described below: Bearer authentication or Permanent API tokens.

Bearer Authentication

The token will be provided upon Login request with login and password from your personal account. 

In the response, you will get two tokens: access and refresh. 

To manage Server API services, add your access token after Bearer in the authorization header like this:  

Authorization: Bearer eyJ0eXAiOiJKV 

Use the  Refresh request to refresh your access token. 

Steps as an example: 

  1. You authorize in your backend using your username and password: https://api.gcore.com/docs/account#tag/Account/paths/~1auth~1jwt~1login/post 
  2. You get two token values: "access" and "refresh".  
  3. The "access" token is a token that is active for several hours (24 hours, but we recommend updating every 4 hours). 
  4. You pass the auth headers into each endpoint: 'Authorization': Bearer ${token} '. 
  5. If the token is correct, everything is fine. 
  6. If not, then a 401 error will be returned.

 

Example:

curl -L -X GET 'https://webrtc3.gvideo.co/rooms/serv1l8bsg8zw/durationOfBroadcast' -H 'Authorization: Bearer eyJ0eXAiOiJKV'

Authentication of Participants and Access Limitation

We allow integration with your user control systems. It could be an external CMS, LMS or any security server. You can verify every user who enters a room.

Our server calls the method specified in &accessUrl attribute. Your server should return code as below. Based on the code, the system allows access to the room or doesn't.

If the access to the specified method is protected via Basic authorization, you need to register a required header in the attribute &authorizationAccess=<header>.

These debugging attributes can be used in the URL. But for public use, you need to inform us to register methods on the server.

Example:

https://meet.gcore.com/call/44fde071&displayName=user16&accessToken=caa630bb&peerId=de9b6927&apiEvent=https://dev.com/api/events&accessUrl=https://dev.com/api/accesscheck

POST

Input values:

  • accessToken – unique security identifier from &accessToken attribute
  • roomId – ID of the room after call/
  • peerId – ID of the participant from &peerId attribute

Example:

{"accessToken":"caa630bb","roomId":"44fde071","peerId":"de9b6927"}

Output codes we require from you:

Code Response Label Description
200 OK A participant is allowed to join the room.
400 Bad Request Token, roomId, peerId not found.
401 Unauthorized A participant is not allowed to join the room, access declined.
403 Forbidden Invalid token.
404 Not found Invalid room ID.
409 Conflict Another connection with an existing peerId was found. In this case, a new connection is established. The previous connection is terminated, and its users get the message: "Someone joined into the room with your ID".
423 Locked Access is closed temporarily or permanently for locked rooms after you close it or limit the maximum number of participants. It is to display a human readable message about the reason and contact info for a moderator, instead of the "Access denied" message.
425 Too Early Access is closed temporarily for those events that have not yet started. We display a human readable message "The event has not started yet. Start % d%." Start time is taken from a JWT.
500 Internal Server Error Server connection error.

More examples:

  • How to prevent unregistered users from joining – send 401 Locked for requests with empty peerId.
  • How to close a room after the event is over – send 423 Locked for all requests after the event is over.
  • How to limit the maximum number of participants – send 423 Locked for all requests after the maximum is reached, resend 200 OK for a room with decreasing number of participants when someone leaves.

Troubleshooting

JWT Digital Signature Algorithm

We use RS256 or HS256 algorithm for signing and generating hash. RS256 refers to the SHA256 hash function (RFC states). 

"alg" Param Value Digital Signature Algorithm
RS256 RSASSA-PKCS1-v1_5 using SHA-256
HS256 HMAC using SHA-256

Please use https://jwt.io/ to verify your JWT tokens.

RS256

RS256 refers to the SHA256 hash function. (RFC states).

RSA key of size 2048 bits or larger must be used with this algorithm.

The RSASSA-PKCS1-v1_5 SHA-256 digital signature is generated as follows: generate a digital signature of the JWS Signing Input using RSASSA-PKCS1-v1_5-SIGN and the SHA-256 hash function with the desired private key. This is the JWS Signature value.

Please see "RSA Public & Secret Key generation" section below for details.

HS256 

A key of the same size as the hash output (for instance, 256 bits for "HS256") or larger MUST be used with this algorithm. 

RSA Public & Secret Key generation

Keys can be generated by any RSA keygen tool. If you don’t know what to do, we recommend using the OpenSSL tool.

To perform the following actions for Windows or Linux, check and/or install OpenSSL on your system.

Commands to generate secret key and export public key:

openssl genrsa -out key_name.key 2048
openssl rsa -in key_name.key -pubout -outform PEM -out key_name.key.pub

File key_name.key.pub will contain public part of the key. File key_name.key will contain the private part of the key.

Note: The number "2048" in the above command indicates the size of the private key. You can choose one between 2048 and 4096 (these numbers represent bits). The larger sizes offer greater security, but this is offset by a penalty in CPU performance. We recommend the best practice size of 2048. It seems like 2048 bits is enough for the foreseeable future (2030 horizon).

Was this article helpful?

Not a Gcore user yet?

Explore the Streaming Platform by Gcore

Go to the product page