MyMLH v4 API Documentation

Welcome to the documentation for Version 4 of the MLH Login system. This system provides developers with a streamlined way to implement user authentication and access user data for MLH-related events and services.

Introduction

The MLH Login system uses OAuth 2.0 to allow applications to authenticate users and request permission to access their data via the MLH API. This version (V4) introduces several changes and improvements over the previous version.

Client Libraries

We provide MLH maintained client libraries for a variety of programming languages.

Library	Link
`omniauth-mlh` (Ruby)	https://github.com/MLH/omniauth-mlh
`passport-mlh-oauth2` (NodeJS)	https://github.com/MLH/passport-mlh-oauth2

OAuth 2.0 Flow

MLH Login supports the following OAuth 2.0 flows:

Authorization Code Flow
Refresh Token Flow

Note: The Implicit Grant flow has been removed in Version 4.

Authorization Endpoint

You may authorize a user's MyMLH account with the following OAuth URL:

https://my.mlh.io/oauth/authorize

Your authorization request must contain the following URL parameters, which should be properly encoded:

Parameter	Description
`client_id`	Your MyMLH Application's Client ID.
`redirect_uri`	Your application's callback redirect URL (which must be pre-registered in our developer portal).
`response_type`	MyMLH will only return '`code`' as our supported response_type.
`scope` (optional)	A whitespace-delimited list of scopes your application is requesting. You may find a full list of potential scopes below. The only default scope is `public` if this is left blank.
`state` (optional)	You may provide a pass-through string for identification and/or to protect against cross-site request forgery (CSRF) attacks.

Once the user logs in to their MyMLH account and Authorizes your application, they will be redirected to your provided redirect_uri with the following parameters:

Parameter	Description
`code`	The authorization code, which may be exchange for an access token.
`state`	If you provided a `state` parameter in your request, it is returned here for verification.

Scopes

MyMLH V4 introduces a new set of granular scopes to control access to user data. When requesting authorization, specify the desired scopes to access specific user information.

Scope	Description
`public`	Grants read-only access to public information (included by default)
`offline_access`	Enables applications to access and use a refresh token to renew access
`user:read:profile`	Access the user's profile (always included with any `user` scope)
`user:read:address`	Access the user's shipping address
`user:read:birthday`	Access the user's birthday
`user:read:demographics`	Access the user's demographics
`user:read:education`	Access the user's education history
`user:read:email`	Access the user's primary email
`user:read:employment`	Access the user's employment history
`user:read:event_preferences`	Access the user's event preferences (dietary restrictions, t-shirt size, etc.)
`user:read:phone`	Access the user's primary phone number
`user:read:social_profiles`	Access the user's social profiles

Token Endpoint

Your application may make a request to the token endpoint to get an access token that can be used to pull permitted user data from the MLH API.

https://my.mlh.io/oauth/token

Your request must contain the following parameters (all are required):

Parameter	Description
`grant_type`	The type of grant being used, may be either `authorization_code` for your initial request or `refresh_token` if you need a new token for offline access.
`client_id`	Your MyMLH Application's Client ID.
`client_secret`	Your MyMLH Application's Client Secret. This is effectively your app's password - keep it safe!
`code`	The `code` you received from the authorization flow callback.
`redirect_uri`	Include the same `redirect_uri` as in the authorization flow request.
In response, you will receive a JSON object containing the following parameters:

Parameter	Description
`access_token`	This is the token that your application can use to retriever user data from the MLH API.
`token_type`	Currently, this will always return `Bearer`
`expires_in`	The number of seconds until the access token expires.
`refresh_token`	If you requested the `offline_access` scope you will be provided with this token that your application can use to obtain a new access token in future.
`scope`	The scopes granted by the user to your application.

MLH API Endpoints

User Information

To retrieve user information about the currently authorized user, use the following endpoint:

GET https://api.mlh.com/v4/users/me

You must include an Authorization header with Bearer <access_token> as the contents from your previous token step.

You may also include the expand URL parameter in an array format. See the NodeJS example below for how this should be structured:

const response = await axios.get(
  "https://api.mlh.com/v4/users/me?expand[]=education&expand[]=professional_experience",
  {
    headers: {
      'Authorization': 'Bearer ' + ${req.user.accessToken},
    },
  }
);

Note: The /users endpoint from MyMLH V3 is no longer available in Version 4.

If your application needs to store user data (for hackathon registrations, for example) we recommend storing the relevant data your application needs at the moment that a user authorizes it. You may update it asynchronously using refresh tokens and the offline_access scope.

Options for expandable data:

Expand Option	Description
`professional_experience`	Provides an array of the user's current and past employers.
`education`	Provides an array of the user's current and past educational institutions.
`address`	Provides a user's shipping address.

When you make your API request, you will receive back a user object in the following JSON format:

{
  "id": "c2ac35c6-aa8c-11ed-afa1-0242ac120002",
  "created_at": 1374710400,
  "updated_at": 1690243200,
  "first_name": "Jane",
  "last_name": "Hacker",
  "email": "[email protected]",
  "phone_number": "+15555555555",
  "profile": {
	"country_of_residence": "US",
    "race_or_ethnicity": "White",
    "gender": "Female",
    "age": 21
  },
  "address": {
    "id": "a2ac35c6-aa8c-11ed-afa1-0242ac122222",
    "line1": "123 Hacker Way",
    "line2": "Apt. 1337",
    "city": "Hackertown",
    "state": "NY",
    "postal_code": "12345",
    "country": "US"
  },
  "professional_experience": [
    {
      "id": "c2ac35c6-aa8c-11ed-afa1-0242ac121234",
      "current": true,
      "employer_name": "ACME Corporation",
      "company": "a2ac35c6-aa8c-11ed-afa1-0242ac125432",
      "title": "DevOps Intern",
      "type": null,
      "start_date": 1314835200,
      "end_date": null
    },
    {
      "id": "d2ac35c6-aa8c-11ed-afa1-0242ac121234",
      "current": false,
      "employer_name": "ACME Corporation",
      "company": "a2ac35c6-aa8c-11ed-afa1-0242ac125432",
      "title": "MLH Fellow",
      "type": null,
      "start_date": 1314835200,
      "end_date": 1396224000
    },
  ],
  "education": [
    {
      "id": "s2ac35c6-aa8c-11ed-afa1-0242ac121234",
      "current": false,
      "school_name": "MLH Fellowship",
      "school_type": "other",
      "start_date": 1314835200,
      "end_date": 1396224000,
      "major": "Site Reliability Engineering"
    },
    {
      "id": "s2ac35c6-aa8c-11ed-afa1-0242ac125432",
      "current": true,
      "school_name": "Hacker University",
      "school_type": "university",
      "start_date": 1314835200,
      "end_date": 1396224000,
      "major": "Computer Science"
    }
  ]
}

Example Usage

Here's an example of how to initiate the OAuth 2.0 flow:

Redirect the user to the authorization endpoint:

https://my.mlh.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&response_type=code&scope=user%3Aread%3Aprofile%20user%3Aread%3Aemail

After the user grants permission, they will be redirected to your redirect_uri with an authorization code.
Exchange the authorization code for an access token:

POST https://my.mlh.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback

Use the access token to request user information:

GET https://api.mlh.com/v4/users/:id
Authorization: Bearer ACCESS_TOKEN

Migrating from V3

If you're migrating from Version 3 to Version 4, please note the following changes:

The Implicit Grant flow has been removed. Use the Authorization Code flow instead.
The /user endpoint has been replaced with `https://api.mlh.com/v4/users/me.
The /users endpoint is no longer available. You must save each user's data one by one in your application as they authorize.
New granular scopes have been introduced. Review the Scopes section and update your authorization requests accordingly.
Review and update your API calls to use the new endpoint structure.

For any questions or issues during migration, please contact the MLH Engineering Team for support.