Authentication

MeetingBurner® OAuth authentication.

OAuth is a protocol that lets external apps request authorization to private details in a user's MeetingBurner® account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.

All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

The MeetingBurner® OAuth server grants access to a user/vendor by issuing an access_token. Like a locked door that can open in multiple ways - such as with a key or passcode - the OAuth server can support multiple grant types to provide access.

This document will explain the flow of using OAuth from a 3rd party website.

Note: If you want to use the MeetingBurner® API just for individual account access, you can generate a Personal Access Token and skip the below processes.

Web Application Flow

This is a description of the OAuth2 flow from 3rd party web sites.

1. Redirect users to request MeetingBurner® access

Used to obtain an authorization code. If the user has not already signed in, they will be redirected to /oauth/signin.

https://www.enterthemeeting.com/oauth/index
Parameters
Parameters
Type Description
client_id Required. The client ID you received from MeetingBurner® when you registered your app.
redirect_uri Required. The redirect_uri must match the client provided endpoint. This parameter must be urlencoded.
response_type Required. Must be code.
state Optional. The state provides you a way to send data you need to get back. Examples are user identification, session id, or any other url encoded data. This same data will be sent back with the code to retrieve access tokens.
owner_type Optional. If you are acting on behalf of a vendor account, then you must include and set to vendor.

2. MeetingBurner® redirects back to your site

If the user accepts your request, MeetingBurner® redirects back to your site with a temporary code in a code parameter. Exchange this code for an access token with the /oauth/accesstoken route.

POST https://www.enterthemeeting.com/oauth/accesstoken
Parameters:
Parameters
Type Description
client_id Required. The client ID you received from MeetingBurner® when you registered.
client_secret Required. The client secret you received from MeetingBurner® when you registered.
code Required. This was sent to you in the /oauth/index redirect.
redirect_uri Required. Must be identical to the one used in the /oauth/index request.
grant_type Required. Must be authorization_code.

In this example POST, -X specfies the HTTP verb and -d specify data.

$ curl -X POST https://www.enterthemeeting.com/oauth/accesstoken \
               -d "client_id=878518e02c5e4bbf38784a0644db99feabe55a89" \
               -d "client_secret=6aff8f3bf1c273293c6536ed5e334609a5a0bf36" \
               -d "redirect_uri=http://www.mywebsite.com/callback_route.php" \
               -d "grant_type=authorization_code" \
               -d "code=nELDUs1Qscz2Z4P82sXMFreCQQCagVNSq5Tt0KlW"

{
    "access_token": "1lSalOdeDUL1Iq1L2Z6iIHfCZvjQmBXxKEGNZIOX",
    "token_type": "bearer",
    "expires": 1406411164,
    "expires_in": 604800,
    "refresh_token": "ejePMsN0rMBeFSJZXgEOvYmhLc4X0eDgjq7Q7ATB"
}

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

$ curl -H 'Authorization: Bearer IJXYlIOkDEttK7cjk0lWyWHczRzWRCW1p60W5s1Z' https://www.enterthemeeting.com/[api_route]
↑ Top

Grant Types

The MeetingBurner® OAuth server supports the following grant types:

authorization_code
The authorization_code grant type involves two steps. First the user authorizes and approves the application and receive a code. Then this code is exchanged for an access_token. This flow is detailed in Web Application Flow section.

refresh_token
The refresh_token grant type is used when an access_token expires. It involves exchanging a refresh_token (issued in an authorization_code grant response) for a new access_token and refresh_token. This flow is detailed in Refresh Token Flow section.
↑ Top

URL Endpoints

The OAuth server has four endpoints.

HTTP Verb Route Description
GET /oauth/authorize Used in the web application flow to authorize an OAuth client application
POST /oauth/accesstoken Used in the web application flow to issue an access_token
POST /oauth/refreshtoken Used in the refresh_token flow to get a new access_token
GET /oauth/signin Used in the web application flow to authenticate a user
↑ Top

/oauth/authorize

Used to obtain an authorization code. If the user/vendor has not signed in to authenticate, then they will be redirected to /oauth/signin.

Parameters
Type Description
client_id Required. The Client ID you received from MeetingBurner® when you registered.
redirect_uri Required. The redirect_uri must match the client provided endpoint. This parameter must be urlencoded.
response_type Required. Must be code.
state Optional. The state provides you a way to send data you need to get back. Examples are user identification, session id, or any other url encoded data. This same data will be sent back with the code to retrieve access tokens.
owner_type Optional. If you are acting on behalf of a vendor account, then you must include and set to vendor.

For an OAuth server authorization endpoint at https://www.enterthemeeting.com/oauth/authorize with client_id 878518e02c5e4bbf38784a0644db99feabe55a89, and redirect_uri https://www.yourdomain.com/callback_route2.php, the corresponding browser link to start the web flow is:

https://www.enterthemeeting.com/oauth/authorize?client_id=878518e02c5e4bbf38784a0644db99feabe55a89&redirect_uri=http%3A%2F%2Fwww.yourdomain.com%2Fcallback_route2.php&response_type=code
                

If you are a vendor, then the start of the web flow would be:

https://www.enterthemeeting.com.com/oauth/authorize?client_id=878518e02c5e4bbf38784a0644db99feabe55a89&redirect_uri=http%3A%2F%2Fwww.yourdomain.com%2Fcallback_route2.php&response_type=code&owner_type=vendor
                

If the user/vendor has not yet authenticated, they will be redirected to /oauth/signin where they must provide their username/password credentials or if they are a vendor, their access_key/secret_key credentials.

After authenticating, the user/vendor will be prompted with an authorization form asking their permission to let your app connect with their MeetingBurner® account.

When the user clicks on the Approve button, they will be redirected to the provided redirect_uri along with a code value.

Example: https://www.yourdomain.com/callback_route2.php?code=878518e02c5e4bbf38784a06 

Note: The default client callback will automatically connect the issued code to a /oauth/accesstoken request.

The final step is to do a POST call to /oauth/accesstoken using this newly obtained code.

↑ Top

/oauth/accesstoken

The /oauth/accesstoken endpoint exchanges the client credentials and the authorization code received from /oauth/authorize for an access_token.

Parameters
Type Description
client_id Required. The Client ID you received from MeetingBurner® when you registered.
client_secret Required*. The client secret you received from MeetingBurner® when you registered.
code Required. What was sent back in the authorize redirect.
redirect_uri Required. Must be identical to the one used in the authorize request.
grant_type Required. Must be authorization_code.

* The client_secret is required but not verified in the version of the OAuth2 client we are currently using.

Note: The refresh token does expire but has a longer duration then the access_token.

A sample curl call: using the newly acquired code from the /oauth/authorize step and the client_secret looks like:

$ curl -X POST https://www.enterthemeeting.com/oauth/accesstoken \
               -d "client_id=878518e02c5e4bbf38784a0644db99feabe55a89" \
               -d "client_secret=6aff8f3bf1c273293c6536ed5e334609a5a0bf36" \
               -d "redirect_uri=http://www.yourdomain.com/callback_route2.php" \
               -d "grant_type=authorization_code" \
               -d "code=nELDUs1Qscz2Z4P82sXMFreCQQCagVNSq5Tt0KlW"
                

In the call, -X specfies the HTTP verb, -d specify data, and \ is used to show the command across multiple lines. A sample response is:

{
    "access_token": "1lSalOdeDUL1Iq1L2Z6iIHfCZvjQmBXxKEGNZIOX",
    "token_type": "bearer",
    "expires": 1406411164,
    "expires_in": 604800,
    "refresh_token": "ejePMsN0rMBeFSJZXgEOvYmhLc4X0eDgjq7Q7ATB"
}
                
                

Note: It is up to the client to securely store both the access_token and the refresh_token.

↑ Top

/oauth/refreshtoken

The /oauth/refreshtoken endpoint exchanges the client credentials and a refresh_token for a new access_token.

Parameters
Type Description
client_id Required. The Client ID you received from MeetingBurner® when you registered.
client_secret Required*. The Client Secret you received from MeetingBurner® when you registered.
refresh_token Required. The refresh token received in a previously successful /oauth/accesstoken response.
grant_type Required. Must be refresh_token.

* The client_secret is required but not verified in the version of the OAuth2 Client we are currently using.

A sample curl call to obtain a new access_token with a refresh_token is:

$ curl    -X POST https://www.enterthemeeting.com/oauth/refreshtoken \
                    -d "client_id=878518e02c5e4bbf38784a0644db99feabe55a89" \
                    -d "client_secret=6aff8f3bf1c273293c6536ed5e334609a5a0bf36" \
                    -d "refresh_token=ejePMsN0rMBeFSJZXgEOvYmhLc4X0eDgjq7Q7ATB" \
                    -d "grant_type=refresh_token"
                

And the successful response:

{
        "access_token": "IJXYlIOkDEttK7cjk0lWyWHczRzWRCW1p60W5s1Z",
        "token_type": "bearer",
        "expires": 1408487234,
        "expires_in": 2678400
}
                

↑ Top

Web Application Flow Diagrams

Authorization Code Grant Flow

              +--------+                                           +---------------+
              |        |--(A)---- Authorization ------------------>|               |
              |        |       /oauth/authorize OR                 |               |
              |        |       /oauth/signin then /oauth/authorize |               |
              |        |                                           |               |
              | Client |<-(B)----------- Code ---------------------| Authorization |
              |        |               or error message            |     Server    |
              |        |--(C)---- Access token request------------>|               |
              |        |       /oauth/accesstoken                  |               |
              |        |                                           |               |
              |        |<-(D)----------- Access Token -------------|               |
              |        |               & Refresh Token             |               |
              +--------+               or error message            +---------------+
            

Refresh Token Flow

              +--------+                                           +---------------+
              |        |--(A)---- Refresh token ------------------>|               |
              |        |       /oauth/refreshtoken                 |               |
              |        |                                           |               |
              | Client |<-(B)----------- Access Token -------------| Authorization |
              |        |              or error message             |     Server    |
              |        |                                           |               |
              |        |                                           |               |
              +--------+                                           +---------------+
            
↑ Top

Accessing Protected Resources

Accessing resources with the OAuth token follows this basic flow:

+--------+                              +----------+
|        |--(A)---- API Request with -->|          |
|        |        Access Token in       |          |
|        |        Authorization Header  | Resource |
| Client |                              | Server   |
|        |<-- (B) Protected Resource ---|          |
|        |      or error message        |          |  
|        |                              |          |
|        |                              |          |
+--------+                              +----------+

To use the API, include the access_token in an Authorization header:

Authorization: Bearer [YOUR-OAUTH-ACCESS-TOKEN]

An example using curl, where -H specifies a header:

$ curl https://www.enterthemeeting.com/rest/1/[route] -H 'Authorization: Bearer IJXYlIOkDEttK7cjk0lWyWHczRzWRCW1p60W5s1Z'

Please refer to API usage examples.

↑ Top

Error Responses

Here are some common error responses.

  • A missing or invalid parameter value. The offending parameter is specified, such as the response below which says to check the client_id.

    {
        "error": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"client_id\" parameter."
    }
                    
  • The user/vendor denied authorization to the client.

    {
        "error": "access_denied",
        "error_message": "The resource owner or authorization server denied the request."
    }
                        

    The error response might also be in the callback URL query string. For example:

    https://www.yourdomain.com/default_oauth_callback.php?error=access_denied&error_message=The%20resource%20owner%20or%20authorization%20server%20denied%20the%20request.
  • Invalid/unknown client_id

    {
        "error": "invalid client_id",
        "error_message": "invalid client_id: 878x518e02c5e4bbf38784a0644db99feabe55a89"
    }
                
  • During the /oauth/accesstoken call you may recieve this error which can be caused by a client_id, redirect_uri or grant_type that does not align with the issued code or a code that has already been used for an access_token. It can also occur if you are using an invalid code.

    {
        "error": "invalid_grant",
        "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. Check the \"code\" parameter."
    }
                    
↑ Top