BlueJeans is being sunset. Please refer to more details

3 Legged OAUTH

The authorization code flow is used by the application to request BlueJeans user access to authenticate third-party applications. There may be applications where users choose to include the BlueJeans feature in their client sessions. 

To understand OAuth's three-legged authentication protocol, let's look at an example of a BlueJeans user who wants to access the BlueJeans functionality and view it in a third-party application. When the third-party application prompts for the BlueJeans credentials, the user authenticates the third-party application and grants the necessary permissions to access the BlueJeans functionality.

Developers who want to integrate their applications must follow the authentication process. The scope parameters during the authentication process are described below.

A three-legged OAuth flow allows an application to act on behalf of another user. To do this, BlueJeans will display an OAuth screen.

  • Configure Your Application
  • Request an Authorization Code (Access code)
  • Get Access token

Configure Your Application:

The first step you must do is register your client application with BlueJeans. This will ensure that BlueJeans knows there is a target application that is requesting an access token.

To register the application, you must obtain the Client ID and Secret ID.

To get the client_id and secret_id, you can reach out to your enterprise administrator. Below is a sample example to get the client_id and client_secret. The authorization token can be either a user token or an application token (admin use-cases), details of which can be found here.

The configuration/registration of the application is done only once by the enterprise administrator. After that, customers can authorize this application according to OAuth standards.

Curl Command

HTTP Method: POST

URL Path

[POST] https://api.bluejeans.com/v1/user/(user_id)/developer_applications

Sample Request 

[POST] "https://api.bluejeans.com/v1/user/514..../developer_applications' \
    
  -H "accept: application/json"
       -H "content-type: application/json" 
       -H "authorization-type:  Bearer access_token"
--data-raw '{
    "appName": "testing100",
    "description": "3-legged authentication",
    "appLogoUrl": "https://..............png",
    "redirectUrls": [
        "https://www.example.com/",
        "https://www.example.com/callback"
    ]
}

Note

In the above example, use as an access token your user token or an application token in the application bearer.

HTTP Header

BlueJeans REST API messages must contain certain formatting values in order to be recognized as a valid calls. Make sure that every REST call includes the following fields:

A couple of HTTP headers are required:

Header

Value
Content-Type application/json
Accept application/json
Authorization Bearer access_token

Body

{
  appName : "appName",
  description : "Reference Application to test 3-legged authentication",
  appLogoUrl : "https://..............png",
  redirectUrls : [
    "https://..............com"
  ]
}

Response

When valid details are provided, the service generates client_id and client_secret. The same is returned to the user.

{
    "description": "This is the first application.",
    "appName": "app-with-encoded-password-1",
    "appLogoUrl": null,
    "redirectUrls": [
      "http://.............................html"
    ]
    client_id :  "43………………………………ec",
    client_secret : "************",
 }

Note

Make sure to retain “client_id and client_secret” for future references as it is displayed only once. Database stored the encrypted format of this key. Just in case, you lose this key - use API “Regenerate CLIENT_SECRET key” to generate a new “client_secret” key.

Request an Authorization Code (Access code)

Now the user needs to log in to BlueJeans and grant access to the application created above. To do this, create a query parameter for the following URL and load the URL into your browser

[GET] https://api.bluejeans.com/oauth2/authorize?clientId=<client-id>&redirectUri=<url-to-receive-auth-code>
           &state=<state>&scope=<scope>&responseType=code&appName=<app-name>&appLogoUrl=<url>

Sample Request

[GET] https://bluejeans.com/oauth2/authorize?clientId=5c.......................33&redirectUri=http://local........html
&scope=list_meetings%2Cmodify_meetings%2Cuser_info%2Cmeeting_history%2Cmodify_user_info&responseType=code&appName=appName

The URL above will prompt you to log into your BlueJeans account. You can use your BlueJeans credentials to log into your BlueJeans account.

 

Users can approve/deny application access to their BlueJeans accounts. When the user grants access to her/his BlueJeans, an access code is returned by the API call.

Note

When the user grants access, the browser automatically redirects the user to the URL specified by the "redirectUri" parameter.

HTTP Header

BlueJeans REST API messages must contain certain formatting values in order to be recognized as a valid call. Make sure that every REST call includes the following fields:

A couple of HTTP headers are required:

Header

Value
Content-Type application/json
Accept application/json

Note

In the above example, use your access token (user token) or an application token.

Body

&clientId=
&redirectUri=
&state=
&scope=
&responseType=code
&appName=
&appLogoUrl=

Response

When valid details are provided, the service generates client_id and client_secret. The same is returned to the user.

&code=
&state=

Note

  • If the user grants BlueJeans access, the API call will be returned with the access code. This code should be exchanged for an access token quickly. 
  • The access code is a value that you exchange with BlueJeans for an OAuth 2.0 access token in the next step of the authentication process. For security reasons, the access code has a 30-seconds lifespan and must be used immediately. If it expires, you must repeat all of the previous steps to request another authorization code.

Parameter Name

Description
clientId

client identifier obtained in “CreateApplication” stage. 
redirectUri url called with OAuthCode. This has to match or be sub-url as registered in “CreateApplication” stage. More in “redirect” step below.
state client application-specific state that is returned back as a parameter in redirect url
scope

Requested permissions by the application

list_meetings,modify_meetings,user_info,meeting_history,modify_user_info
responseType The value of this field should always be code.
appName This is the name of the application associated with the client_id key.
appLogoUrl This is a url to where BlueJeans can find a bitmap image to show on the confirm/reject dialog (disabled for now)
code This is a unique identification code that BlueJeans returns when the user approves access to the Application
state This is an echoing of the arbitrary string passed into BlueJeans If it does not match the calling state, then this may indicate a phishing incident.

Get Access Token

In this step the user Application session makes an API call to exchange the access code for a user access token Along with this API call, you must pass the access code obtained from the Authorization step.

[POST] "https://api.bluejeans.com/oauth2/token?Code"
[POST] "https://api.bluejeans.com/oauth2/token?Code"
              -H "accept: application/json"
              -H "content-type: application/json"
              -H "authorization-type:  Bearer access_token={your access_token}"
              -d "{\"redirectUri\": \"https://www.example.com/authenticated\", \"code\": \"gqNe....skFCK\", 
                     \"grant_type\": \"authorization_code\", \"client_secret\": \"xxxxxxxxx\", 
                     \"client_id\": \"43160b2...989bec\" }"

HTTP Header

BlueJeans REST API messages must contain certain formatting values in order to be recognized as a valid call. Make sure that every REST API call includes the following fields:

A couple of HTTP headers are required:

Header

Value
Content-Type application/json
Accept application/json

Note

You must use an HTTP POST request and pass all of the fields below, such as the client_secret field, in the request body. Do not pass any of these fields as query string parameters.

Body

{
  redirectUri   : "https://example.com/authenticated",
  code          : "gqNe....skFCK",
  grant_type    : "authorization_code",
  client_secret : "xxxxxxxxx",
  client_id     : "43160b2...989bec"
}

Response

After the successful execution of the sub-steps below, HTTP (OK) response with the following token(JSON) is returned back to a client application. The significant attributes are as follows.

{
    "access_token": "cab95......92a2d",
    "expires_in": 3600,
    "scope": {
        "user": ******,
        "appPermissions": [
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/personal_meeting.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/scheduled_meeting.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/meetings/.*/numbers.*"
            },
            {
                "method": "PUT",
                "allowedRegex": "/v\\d+/user/******/personal_meeting.*"
            },
            {
                "method": "POST",
                "allowedRegex": "/v\\d+/user/******/scheduled_meeting.*"
            },
            {
                "method": "PUT",
                "allowedRegex": "/v\\d+/user/******/scheduled_meeting.*"
            },
            {
                "method": "DELETE",
                "allowedRegex": "/v\\d+/user/******/scheduled_meeting.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/billing.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/room.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/?"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/features.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/enterprise_profile.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/passcodeStatus.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/featurepolicies.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/delegators.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/attributes.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/partnerInfo.*"
            },
            {
                "method": "PUT",
                "allowedRegex": "/v\\d+/user/******/featurepolicies.*"
            },
            {
                "method": "PUT",
                "allowedRegex": "/v\\d+/user/******/?"
            },
            {
                "method": "PUT",
                "allowedRegex": "/v\\d+/user/******/room.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/meeting_history.*"
            },
            {
                "method": "GET",
                "allowedRegex": "/v\\d+/user/******/cms.*"
            }
        ],
        "partitionName": "z62",
        "partition": {
            "id": 29,
            "name": "z62"
        },
        "bearerPermissions": "list_meetings,modify_meetings,user_info,meeting_history,modify_user_info",
        "clientId": "dc1a........4d83",
        "client_id": "dc1a9......4d83",
        "capabilities": []
    },
    "refresh_token": "6dTGy...........wwg1"
}

Parameter Name

Description
clientId

client identifier obtained in “CreateApplication” stage. (or)

Client ID is the OAuth key corresponding to this application
redirectUri One of the registered url or sub-url of registered urls. Has to be same as passed in “Get Access Code” step above.
grant_type This field should alrways to be "authorization_code"
code This is a unique identification access code generated by OAuthService. This one is used by the client application to obtain Bearer Token. This code is valid only for 30 seconds. 
client_secret Client Application secret. As obtained from “CreateApplication” step.
access_token This is the user access token that you will use for API calls (e.g. getting a list of scheduled meetings).
expires_in Validity time for the token in seconds. It will be 1 hour for 3-legged tokens.
appPermissions This array of objects outlines authorized functions and URI locators for those functions.
partitionName This Object contains partition information.
id This integer is the number of the user's partition.
name This string is the name of the user's partition.
bearerPermissions Stores the information about the permitted scopes. The array of strings lists what functions this access token enables
capabilities TBD
refresh_token refresh token. This has a validity of 60 days. It is used to refresh the token should the “access_token” expire. 

You can use the received access_token to make REST API calls according to the scope. Using this access token in the API request, you can get the list of meetings, modify meetings, create meetings, get user information and meeting history, and modify user information.

A sample REST API call that your application can call on behalf of the user with the received access token.

Get Personal meeting

The below endpoint gets the settings for a user’s personal meeting.

{
 "method": "GET",
 "https://api.bluejeans.com/v1/user/{user_id}/personal_meeting?" 
                                   -H "accept: application/json"
                                   -H "content-type: application/json"
                                   -H "authorization-type:  Bearer access_token"

            }

List Meetings

The below endpoint gets a list of the user’s scheduled upcoming meetings.

{
 "method": "GET",
 "https://api.bluejeans.com/v1/user/{user_id}/scheduled_meeting?access_token=cab95......92a2d" 
                                       -H "accept: application/json"
                                       -H "content-type: application/json"
                                       -H "authorization-type:  Bearer access_token"
            }

Get Meetings Email

The below endpoint retrieves the email object for a scheduled meeting

{
 "method": "GET",
 "https://api.bluejeans.com/v1/user/{user_id}/scheduled_meeting/{meeting_id}/emails" 
                           -H "accept: application/json"
                           -H "content-type: application/json"
                           -H "authorization-type:  Bearer access_token"
            }

Get Meetings Join Info

The below endpoint retrieves the email object for a scheduled meeting

{
 "method": "GET",
 "https://api.bluejeans.com/v1/user/{user_id}/meetings/{meeting_id}/numbers" 
                                         -H "accept: application/json"
                                         -H "content-type: application/json"
                                         -H "authorization-type:  Bearer access_token" 
            }

Update Personal meeting

The below endpoint changes the settings for a user’s personal meeting.

{
 "method": "PUT",
 "https://api.bluejeans.com/v1/user/{user_id}/personal_meeting" 
                               -H "accept: application/json"
                               -H "content-type: application/json"
                               -H "authorization-type:  Bearer access_token" 
 }

Create Meeting

The below endpoint will create a scheduled meeting.

{
 "method": "POST",
 "https://api.bluejeans.com/v1/user/{user_id}/scheduled_meeting" 
                      -H "accept: application/json"
                      -H "content-type: application/json"
                      -H "authorization-type:  Bearer access_token" 
 }

Update Scheduled meeting

The below endpoint changes the settings for a user’s personal meeting.

{
 "method": "PUT",
 "https://api.bluejeans.com/v1/user/{user_id}/scheduled_meeting{meeting_id}" 
                           -H "accept: application/json"
                           -H "content-type: application/json"
                           -H "authorization-type:  Bearer access_token" 
            }

List History by User

The below endpoint retrieves a list of meeting histories by the given user.

{
 "method": "GET",
 "https://api.bluejeans.com/v1/user/{user_id}/meeting_history?meetingId=51****"
                           -H "accept: application/json"
                           -H "content-type: application/json"
                           -H "authorization-type:  Bearer access_token" 
 }

Get Enterprise Profile

The below endpoint retrieves the enterprise profile associated with the user.

{
  "method": "GET",
  "https://api.bluejeans.com/v1/user/{user_id}/enterprise_profile"
                            -H "accept: application/json"
                            -H "content-type: application/json"
                            -H "authorization-type:  Bearer access_token" 
 }

Get Recording Download Link

The below endpoint retrieves properties about the recording chapter.

{      
 "method": "GET",   
 "https://api.bluejeans.com/v1/user/{user_id}/cms/1234567?isDownloadable=true&isDisabledContentAllowed=true"
                                     -H "accept: application/json"
                                     -H "content-type: application/json"
                                     -H "authorization-type:  Bearer access_token" 
 }