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

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
• /users

/user

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

Parameters

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

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.

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

School

Permissions

You can only access a school through a user object.

Fields

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.