For Web Apps

Overview

1. Redirect browser to the /oauth2 endpoint
2. User will be prompted to accept your OAuth 2.0 request
3. We redirect browser to your application's redirect_uri; parse Authorization Code from the URL query string
4. POST the Authorization Code, along with your client credentials, to our /token endpoint. This must be done from your server--your client_secret should never be exposed to a browser.
5. We respond with a JSON containing access_token + refresh_token
6. Refresh access_token when it expires

OAuth 2.0 Endpoint

URL

https://secure.join.me/api/public/v1/auth/oauth2

Method

GET
Open in full window or popup -- not iframeable

Query Parameters

Note: When the initial request is made, parameters are validated before the user is directed to log in. Any missing parameters or parameters in invalid format will be reported via an error page. If an error occurs during the subsequent OAuth 2.0 flow, the user agent is redirected to the URL defined in the redirect_uri parameter with the error description in the URL fragment.

Example Request URL

https://secure.join.me/api/public/v1/auth/oauth2?client_id={api_key}&scope=scheduler%20start_meeting&redirect_uri=https://domain.com/callback&state=ABCD&response_type=code

Authorization Code Response

Response will be provided via the URL query string. It is recommended that this is parsed server-side, since the Authorization Code must be exchanged for an access_token via a server-to-server API request.

Example Success Response

https://example.com/redirect.html?code={Authorization Code}&state={your state}

Example Error Response

https://example.com/redirect.html?error=access_denied&state={your state}

Token Endpoint

URL

https://secure.join.me/api/public/v1/auth/token

Method

POST
This request must come from your server to preserve client_secret

Parameters

These parameters should be JSON or x-www-form-urlencoded, in the body of the POST request

Example Request

Request

{
    "client_id": "qwer1234",
    "client_secret": "asdf5678",
    "code": "zxcv90",
    "redirect_uri": "https://example.com/redirect",
    "grant_type": "authorization_code"
}

Example Response

{
    "access_token": "qwer1234",
    "token_type": "bearer",
    "return_type": "json",
    "refresh_token": "asdf5678"
}

Refresh

To refresh an access_token, you'll call the same /token endpoint, but with slightly different parameters. You will need to refresh your tokens when you receive an HTTP 401 response from an API endpoint (indicating the access_token is expired).

Note: Your refresh_token is invalidated during this flow--successful refresh will create a new access_token + refresh_token pair, and you should use this new refresh_token for the next refresh request.

The refresh_token, like client_secret, is also confidential--do not expose this to the browser.

URL

https://secure.join.me/api/public/v1/auth/token

Method

POST
This request must come from your server to preserve client_secret + refresh_token

Parameters

These parameters should be JSON or x-www-form-urlencoded, in the body of the POST request

Example Request

{
    "client_id": "qwer1234",
    "client_secret": "asdf5678",
    "refresh_token": "zxcv90",
    "redirect_uri": "https://example.com/redirect",
    "grant_type": "refresh_token"
}

Example Response

{
    "access_token": "qwer1234",
    "token_type": "bearer",
    "return_type": "json",
    "refresh_token": "asdf5678",
    "scope": "user_info scheduler start_meeting"
}