FAQ

Are there any code samples available?

Yes, we have a sample Kitchen Sink App which demostrates all the v1 API functionality. We have also built a join.me OAuth 2.0 module for hello.js, designed to simplify the OAuth implementation process.

What HTTP headers are required?

Every request to an API endpoint (except the /auth endpoints) should include two HTTP headers:

Content-Type: application/json

Authorization: Bearer {OAuth 2.0 access_token}

What is my application Callback URL, and why is it required?

During the OAuth 2.0 flow, you will temporarily redirect your user to join.me in order to sign in and authorize your application. After the user accepts this authorization request, join.me will return the browser to your Callback URL (aka redirect_uri in OAuth 2.0 terminology) with a newly created access token as part of the URL fragment query string. Our authorization page has more information.

What values are acceptable for the Callback URL?

You can use any URL you control. The browser never sends back the values in the URL fragment, but make sure that whenever you send the access token over the internet you're using HTTPS to secure it.

What about the Builder page?

The Builder page is a special case: since we're intercepting the callback to populate all the test API calls with the access_token, you'll need to temporarily change your application's Callback URL to https://developer.join.me/io-docs/oauth2callback if you want to use it. Make sure your application isn't live though, because changing the Callback URL may cause validation errors for any real user trying to authorize you application via OAuth 2.0 (it may be safer to create a test application instead).

What does an HTTP 403 mean?

Symptom

An API call results in a 403 error and returns the following HTTP headers:

HTTP Response Header

Server: Mashery Proxy
WWW-Authenticate: Bearer realm="api.join.me", error="invalid_token"
X-Error-Detail-Header: Account Inactive
X-Mashery-Error-Code: ERR_403_DEVELOPER_INACTIVE

Response Body

<h1>Developer Inactive</h1>

Cause

This error indicates that your OAuth 2.0 access_token is invalid, or your Bearer Authorization header is incorrectly formatted.

Solution

Verify your Authorization header, and if necessary, use our Builder and inspect the headers that it sends with each request.

What does an HTTP 401 mean?

Symptom

An API call results in a 401 error and returns the following JSON response:

Response Body

{
    Message: "Not authorized",
    ErrorCode: "forbidden"
}

Cause

The access token is no longer valid because the user has revoked your application's OAuth 2.0 permissions.

Solution

If you have a refresh token for this user, you can use this to get a new access_token. Otherwise, you will need to send the user into the initial OAuth 2.0 permission workflow again, and try to re-request permission to access their account info.

What does an HTTP 400 mean on refresh?

Symptom

You tried to use your refresh token, but received an HTTP 400 response.

Response Body

{
    "error": "invalid_refresh_token",
    "error_description": ""
}

Cause

Your refresh token is invalid (either due to the token being revoked or the token not matching our records).

Solution

You will need to send the user into the initial OAuth 2.0 permission workflow again, and try to re-request permission to access their account info.

What does an HTTP 500 mean?

Symptom

Your API calls are returning HTTP 500 errors, along with a JSON:

{
    "StatusCode":500,
    "ExitPointId":{integer id},
    "Message":"Unknown internal server error.",
    "ReferenceNumber":"d{integer id}"
}

Cause

In general, this could be any unknown server error. However, there is one specific case that will result in this error: When a join.me user revokes your application's OAuth 2.0 permission, there is a ~15 minute propagation delay before API calls are met with an HTTP 401 error.

Solution

Your application can handle HTTP 500 any way that makes sense for your use-case. If you are frequently seeing an HTTP 500 for a particular call, or would simply like more infomation about an error, please Contact Us and include the full error JSON, as well as a summary of the situation (e.g. API endpoint causing the error, parameters used, etc.).

How do I get access to the /v1/presenters endpoints?

The presenters endpoints are part of the Business API plan. In order to sign up for this plan, you will need to contact us directly. Once we approve your request, we will upgrade your Basic API Key to a Business Key. See the Business documentation for more info.