Overview


MyMLH

MyMLH is a platform that allows hackathons and third party hackathons to request authorization to personal information from users who have created an account with MyMLH. Our platform is built using the OAuth 2 protocol which means no passwords are ever exchanged using MyMLH.

As a developer, you'll be able to create an application on MyMLH and you will receive a unique Client ID and Secret. Your Client ID can be made public but your Client Secret should not be shared or made public under any circumstances. Treat your secret like you would your password.

What is OAuth?

OAuth is the open standard for authorization and is widely adopted by all the most trusted and recognised websites in the world. OAuth provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. It specifies a process for resource owners to securely authorize third-party access to their server resources without sharing their credentials.

Want to learn more about OAuth? Check out this video explaining OAuth or visit our Tutorials & Videos section.

Features

Secure

Users never share their passwords with third party applications, increasing account control and security.

Standard

Users only need one MyMLH account which works across all third party applications and events.

Simple

Event registration is no longer a mess of forms or complexity.

Getting Started: Creating a MyMLH Application


Sign In

In order to get started, sign into your account at https://my.mlh.io/login. If you don't have an account, you will need to create one using the Sign Up button. It's completely free to sign up and to use MyMLH.

Registering A New Application

Head over to the Applications Dashboard where you will see all of the applications that you've created. Click on the "Register New Application" button. You will see a screen to register a new application. Fill out the form with the required information. The Redirect URL is where you want MyMLH to redirect back to. This could be a further instructions, a place to upload resumes, or a simple "Thanks for Signing Up" page.

Once that information is filled out, hit the Submit button. You will see your brand new MyMLH OAuth Application. This screen (see below for example) will display your application's information and most importantly the Application ID and Application Secret. The secret shouldn't be shared with anyone ever, keep it safe.

Want to change your application? You can also edit or destroy your application by clicking here.



Hooking It Up To Your Website

Now that you have an application, let's connect it to your website. We're going to be using the Implicit Grant Flow in this example. You will want to direct users to the link below:

https://my.mlh.io/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URL>&response_type=token

Replace <CLIENT_ID> with your MyMLH Application ID and replace <REDIRECT_URI> with the URL that you want us to send our response to you with. Remember to encode the Redirect URL so the browser doesn't misinterpret it and throw an error.

You can include somewhere in your site where someone can click on it. Check out how we did it on this sample app.

Using It

Voila! You're done! Now kick back and wait for users to sign up for your event. You can see who has signed up for your event by using the following /users API. Once again, you'll need to swap in your Client ID and Secret token you received when you created your application:

Call
GET https://my.mlh.io/api/v3/users?client_id=<CLIENT_ID>&secret=<APP_SECRET>
Parameters
Name Type Description
client_id string Required. Your Application ID. This can be found in the Applications Dashboard. Example: arefc6q1e9dhz5mttl43bemf1iwx5rril33m3hkxj05qe0f42h6fhj5uwuvz9cuc.
secret string Required. Your Application Secret. This can be found in the Applications Dashboard. Example: g4j1x68fcf4dmsix2cfghdqg6r01y5z7d8brggmupq09bjdnhty7bgfpn72nso0e.
page integer Optional. The current page of users you want to visit. Default page is 1.
per_page integer Optional. The amount of users to display on a single page. Default per page is 250.

API V3



We have deprecated API v2 from MyMLH on 12 August 2020. You'll need to switch to using the new API in order for it to work again.

What's Changed in V3

We originally set up MyMLH to be the common profile for primarily event registration but the use of MyMLH has expanded past just registrations. Because of that, fields that we collected for event registration are outdated and not helpful. In API V3, we have dropped the use of these event fields. We no longer support the following event fields on the user profile:

  • dietary_restrictions - Previously returned the user's dietary restrictions. This information is not relevant outside the context of in-person events.
  • shirt_size - Previously returned the user's preferred T-shirt size. However, this information changes often and depends on what the events can provide.
  • special_needs - Previously returned any special accommodations needed. Accommodations are highly dependent on the event type of the usage of the application.

What's Changed in V2

After receiving your feedback on MyMLH, we've focused on making V2 more developer-friendly and user-friendly.

  • Developers can now request access to specific information. MyMLH V2 includes the scope parameter, which you can pass through different ranges of scopes to access different levels of information for users. This provides more control to developers and users, providing a better experience. Read more on scopes over here.
  • Pagination comes to API V2. When trying to export all the users who have authorized with your application, it would be slow. We have now introduced a page parameter in the /api/v3/users.json endpoint. Read more on pagination here.
  • We now ask for Level of Study instead of Graduation Date. In API V2, you'll no longer find the graduation column for users. We now ask users to enter a Level of Study, and as such, we now return a level_of_study column with all V2 responses.

V1 to V3 Transitioning Guide

Here's what you'll need to do to upgrade your existing MyMLH integrations to consider the V2 API:

  • To export all users in JSON, you'll need to make multiple requests. Because of pagination, each page by default will only return 250 results. If you have over 250 results, you'll need to use the page parameter in the /api/v3/users.json endpoint to call additional pages which will allow you to make complete exports. The CSV endpoint (/api/v3/users.csv) is unaffected by pagination, so you'll be able to export all of your users in one call as you could in V1.
  • Consider only asking for information you need. Our new scopes feature allows developers to only ask for information they need. MyMLH V3 will ask for all information by default. But if you would like to only ask for a subset of a user's information with MyMLH, you should consider using the scope parameter when directing them to MyMLH to authorize your application (Example: https://my.mlh.io/oauth/authorize?client_id=...&redirect_uri=...&scope=[insert scopes here]).
  • Change your application's behaviour to consider Level of Study and School. MyMLH V2 no longer asks for a graduation date, and as a result no longer returns the graduation column. It is succeeded by a level_of_study column. With schools, we have made changes that'll reduce the amount of erroneous school names being entered. If you continue to use API V1, you should be aware that graduation will still exist but may be null if the user has registered since we introduced Level of Study.

As always, we're here to help. If you need any help with transitioning your existing integration to V3, feel free to reach out to us!

OAuth Flows


MyMLH OAuth Flows

MyMLH is an OAuth 2 provider that supports two different major Grant Types: Implicit and Authorization Code. Depending on your use case, you may prefer one over the other.

  • Authorization Code - This is the recommended OAuth Grant type. It is designed and optimized for server-side authentication. You wouldn't want to use this on your client side application because your application's secret token would be exposed to the world.

  • Implicit - This a Grant Type that you would typically see for a client side or mobile application. Instead of requiring an intermediary server to request the access token, it passed directly to the client in the URL fragment.

Grant Type: Authorization Code

1. Redirect users to sign in with MyMLH

To start the authorization flow, direct the user to the authorize URL for your application. Typically this would happen by the user clicking an "Login with MLH" button. Here's the link format you should use:

GET https://my.mlh.io/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code&scope=email+education+birthday
Parameters

You'll notice some parameters in the query string, we'll explain them below:

  • client_id - This is your application's ID. You can find this on your application's dashboard.
  • redirect_uri - This is where the user will be sent once they've authorized your application. You configured this when you created the application and can change this any time through your application's dashboard.
  • response_type - This parameter determines what Grant Type to respond with. For Authorization Code Grants this should be code.
  • scope - This parameter defines which scopes you would like to ask for. Each scope is separated by +.

2. Application Receives Authorization Code

If the user clicks "Authorize", they'll be sent to the redirect_uri you specified with the code parameter in the query string. For example, if your redirect URI was https://example.com/callback, MyMLH would send the user to the following URL:

GET https://example.com/callback?code=<AUTH_CODE>
Parameters

You'll again notice a parameter in the query string, here's what that does:

  • code - This is your authorization code. You can exchange this for an access token. The authorization code expires after 10 minutes.

3. Exchange the Authorization Code for an Access Token

Now that you have an authorization code, you can exchange that for an access token that you can use to make requests for users. To do that, you'll need to make a POST request to the tokens endpoint like this:

POST https://my.mlh.io/oauth/token?client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&code=<AUTH_CODE>&redirect_uri=<REDIRECT_URI>&grant_type=authorization_code
Parameters
  • client_id - This is your application ID. You can find this on your application's dashboard.
  • client_secret - This is your application's secret key. You can find this on your application's dashboard. Keep it secret, keep it safe.
  • code - This is the code you received from MyMLH in the last step.
  • redirect_uri - This is where the user will be sent once they've authorized your application. You configured this when you created the application.
  • grant_type - This represents the type of code you are sending in. In this case, this should be authorization_code.
Response
{
  "access_token": [ACCESS_TOKEN],
  "created_at": [CREATED_AT],
  "scope": [SCOPE],
  "token_type": "bearer"
}
Parameters

You'll notice some parameters in the response body, here's what those do:

  • access_token - You can use this token to make requests on the user's behalf.
  • created_at - This is when the token was created.
  • scope - A string containing a list of scopes the user has authorized for.
  • token_type - This is the type of token.

Grant Type: Implicit

1. Redirect users to sign in with MyMLH

To start the authorization flow, direct the user to the authorize URL for your application. Typically this would happen by the user clicking a "Login with MLH" button. Here's the link format you should use:

GET https://my.mlh.io/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=token&scope=email+demographics
Parameters

You'll notice some parameters in the query string, here's what those do:

  • client_id - This is your application's ID. You can find this on your application's dashboard.
  • redirect_uri - This is where the user will be sent once they've authorized your application. You configured this when you created the application and can change this any time through your application's dashboard.
  • response_type - This parameter determines what Grant Type to respond with. For Authorization Code Grants this should be token.
  • scope - This parameter defines which scopes you would like to ask for. Each scope is separated by +.

2. Application Receives Access Token

If the user clicks "Authorize", they'll be sent to the redirect_uri you specified with the access_token parameter in the URL fragment. For example, if your redirect URI was https://example.com/callback, MyMLH would send the user to the following URL:

GET https://example.com/callback#access_token=<ACCESS_TOKEN>
Parameters

You'll receive a parameter in the URL fragment, here's what that does:

  • access_token - You can use this token to make requests on the user's behalf.

API Endpoints


The MyMLH API allows you to fetch the information for an individual user or users.

/user

Retrieve a user's information including name, school, email address. Returns a User object.

Parameters
URI Parameter Type Description
access_token string Required. The access token of the user that you want to retrieve. This can be captured from the redirect URI. Example: g4j1x68fcf4dmsix2cfghdqg6r01y5z7d8brggmupq09bjdnhty7bgfpn72nso0e.
Call
GET https://my.mlh.io/api/v3/user.json?access_token=<ACCESS_TOKEN>
Response
{
  "status": "OK",
  "data": {
    "id": 1,
    "email": "[email protected]",
    "created_at": "2015-07-08T18:52:43Z",
    "updated_at": "2015-07-27T19:52:28Z",
    "first_name": "John",
    "last_name": "Doe",
    "level_of_study": "Undergraduate",
    "major": "Computer Science",
    "date_of_birth": "1985-10-18",
    "gender": "Male",
    "phone_number": "+1 555 555 5555",
    "school": {
      "id": 1,
      "name": "Rutgers University"
    },
    "scopes": [
      "email", "phone_number", "demographics", "birthday", "education"
    ]
  }
}

/users

Retrieve the list of users that signed up for your event. Returns an array of User objects.

Parameters
URI Parameter Type Description
client_id string Required. Your Application ID. This can be found in your Application Dashboard.
Example: g4j1x68fcf4dmsix2cfghdqg6r01y5z7d8brggmupq09bjdnhty7bgfpn72nso0e
secret string Required. Your Application Secret. This can be found in your Application Dashboard.
Example: g4j1x68fcf4dmsix2cfghdqg6r01y5z7d8brggmupq09bjdnhty7bgfpn72nso0e
page integer Optional. The current page of users you want to visit. Default page is 1.
per_page integer Optional. The amount of users to display on a single page. Default per page is 250.
Call
GET https://my.mlh.io/api/v3/users.json?client_id=<CLIENT_ID>&secret=<SECRET>&page=1
Response
{
  "status": "OK",
  "data": [{
    "id": 1,
    "email": "[email protected]",
    "created_at": "2015-07-08T18:52:43Z",
    "updated_at": "2015-07-27T19:52:28Z",
    "first_name": "John",
    "last_name": "Doe",
    "level_of_study": "Undergraduate",
    "major": "Computer Science",
    "date_of_birth": "1985-10-18",
    "gender": "Male",
    "phone_number": "+1 555 555 5555",
    "school": {
      "id": 1,
      "name": "Rutgers University"
    },
    "scopes": [
      "email", "phone_number", "demographics", "birthday", "education"
    ]
  }, {
    "id": 2,
    "email": "[email protected]",
    "created_at": "2015-07-08T18:52:43Z",
    "updated_at": "2015-07-27T19:52:28Z",
    "first_name": "Jane",
    "last_name": "Doe",
    "level_of_study": "Undergraduate",
    "major": "Computer Science",
    "date_of_birth": "1985-10-18",
    "gender": "Male",
    "phone_number": "+1 555 555 5555",
    "school": {
      "id": 2,
      "name": "Stony Brook University"
    },
    "scopes": [
      "email", "phone_number", "demographics", "birthday", "education"
    ]
  }],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "results_on_page": 2,
    "results_total": 2
  }
}

API Overview


The MyMLH API is the primary way to retrieve who has signed up for your MyMLH applications. It's a read-only, HTTP-based API that allows you to query users and generate access tokens.

Root

The root for API requests is https://my.mlh.io/api/v3. All requests must be made over HTTPS.

Requests

The MyMLH API is a RESTful API. Authentication is handled through URL parameters. (Example: /api/v3/resource?parameter=value)

Responses

Content-Type

The API currently only returns JSON (JavaScript Object Notation). You can specify a particular MIME type in your Content-Type header when making an API request. The MIME type for JSON is application/json.

Status Codes

Below is a table description of the various status codes we currently support against resources.

Status Code Description
200 HTTP OK. This means your request was successful!
400 Bad request.
401 Requires authentication.
500 Internal server error.

Scopes Reference


In MyMLH API V2, we introduced scopes. Scopes are permission levels that allow you to clearly request particular sets of information with the user's consent. This ensures the user has full clarity and control of what information hackathons & third party applications can access.

For developers, it adds a level of transparency that will make it easier for users to authorize their information with you. And if you ever require additional scopes in the future, you can ask the user to re-authorize to grant additional scopes which will help users have a better understanding of why and when certain information is needed.

To use scopes, you'll need to add the scope parameter to your /oauth/authorize endpoint. See OAuth Flows for more information.

Default Fields

By default, the following fields are always available regardless of the scopes requested:

  • id
  • first_name
  • last_name
  • created_at
  • updated_at

Scopes

The available scopes are as follows:

  • email
  • phone_number
  • demographics
  • birthday
  • education
  • event

To understand what information is exposed from the API with each scope, visit the object reference section.

Objects Reference


User

Permissions

You can access a user with any valid access token.

Fields
Name Type Scope Required Description
id int None The user ID.
email string email The email address that the user logs in with.
created_at string None The time the user was initially created. Conforms to the ISO 8601 format.
updated_at string None The time the user was last updated. Conforms to the ISO 8601 format.
first_name string None The user's first name.
last_name string None The user's last name.
graduation string The user's selected graduation date. Formatted in YYYY-MM-DD. Deprecated in API V2.
level_of_study string education The user's current level of study.
major string education The user's selected major. Find a full list of all majors here.
date_of_birth string birthday The user's date of birth. Formatted to YYYY-MM-DD.
gender string demographics The user's gender. The options are: Female, Male, Non-binary, I prefer not to say, and Other. The Other option allows users to specify their gender.
phone_number string phone_number The user's phone number.
school School education The school that the user is enrolled in.
scopes array None The scopes that were requested for this user. The options can be found here. Introduced in API V2.

School

Permissions

You can only access a school through a user object.

Fields
Name Type Scope Required Description
id int education The school ID.
name string education The name of the school that the user is enrolled in.

Libraries & Resources


Libraries

MLH/omniauth-mlh

The official OmniAuth strategy for MyMLH, making it extremely easy to integrate MyMLH into your existing Ruby/Rails apps.

Examples

MLH/SharkHacks5000

An example of a static hackathon website using MyMLH without a backend. Designed for a easy + quick implementation.

Tools

rohitdatta/pepper

A powerful hackathon application system that is built on MyMLH using virtualenv, Python & PostgreSQL.

hacktx/nucleus

An extensible and comprehensive hackathon application system that integrates with MyMLH, Slack and more.

RitwikGupta/MLHOrganizerDash

A simple MyMLH dashboard written in Python that lets you save your hackathon participants locally and view them.

ghmeier/my-mlh-dashboard

A lightweight, interactive JavaScript MyMLH dashboard that lets you view all of your hackathon participants.

JavaScript View on GitHub

Tutorials & Videos


Our very own Niko Lazaris, who built MyMLH during his summer internship at MLH in 2015, recently did a MLH Office Hours explaining MyMLH.