Leaguevine's logo

Authentication

The Leaguevine REST API uses OAuth 2.0 for authenticating users. If you are a developer, this means you will not need to worry about obtaining and storing user credentials. If you are a regular user, this means you will not have to give your credentials to third party applications.

To get started, first follow the instructions to register your app. Upon completion, we will give you the credentials you need to implement one of the two User Login methods or the App Login method.

Register your app

To use the Leaguevine API, you will need to first register your application. This process is completely free and automated, so it should take just a minute.

User Login

If you have an app that allows users to log into Leaguevine, you will use Leaguevine's OAuth 2.0 server to check their credentials. OAuth 2.0 works differently for different types of API consumers, so each possible flow is explained here.

Method 1: Client-side Apps (Mobile apps, Javascript, etc.)

Use the client-side flow if you are building things such as iPhone apps, Android apps, Javascript widgets, or any other app where the user has access to the code and you do not want to expose your client secret. Any app that is not powered by your own server is considered a client-side app.

Obtain an Access Token

  • Send your users to Leaguevine's login page
    https://www.leaguevine.com/oauth2/authorize/?client_id=YOUR_CLIENT_ID
    &response_type=token
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &scope=universal
  • If the user logs in successfully, they will be redirected to:
    YOUR_REGISTERED_REDIRECT_URI#access_token=ACCESS_TOKEN
    &token_type=bearer
    &expires_in=157680000
    &scope=universal

    You then need to intercept this redirection and read the access token. This access token allows you to make API calls on behalf of the user and is valid for the number of seconds given in the expires_in parameter. For tokens with universal scope (the only scope currently offered), the access_token is good for 5 years or until the user revokes your app's access to their account.

    The redirect_uri in the URLs above is the redirect_uri you specify when you register your app.

    The scope variable determines the amount of permissions this access token will have. The only scope available at the moment is the 'universal' scope.

Make API Calls

https://api.leaguevine.com/v1/games/234/?access_token=ACCESS_TOKEN

iOS

Apple recommends iOS developers to specify a custom redirect_uri. We support these custom URLs so this is the recommended way to authenticate your app. There are many other tutorials online for how to set up a custom URL (for example, try this or this).

After doing that, you can either handle the request and response cycle manually (which is not nearly as hard as it was for OAuth 1.0) or you can make use of one of many OAuth2 iOS client libraries.

Android

Bob Baddeley from Portable Scores implemented a basic Android app to interact with the API. You can view this app on github and use this as a starting point for your own app.

Foursquare also has an example of how to use oauth2 within an android app, see the example given by Foursquare.

There is also an existing OAuth 2 library called leeloo for Java/Android which may be useful.

Performing the integration from scratch for OAuth 2.0 is not nearly as hard as it used to be for OAuth 1.0 so if you don't find online guides or libraries that you like, don't be intimidated. Most of the code in existing OAuth 2.0 libraries was written for creating an OAuth 2.0 server, and the remaining code implements several different OAuth 2.0 flows which we don't even use. Thus, if you are writing your integration from scratch your code would only be a small fraction of what you see in existing libraries. Integrating with Leaguevine is as easy as following the steps to obtaining and using an Access Token above.

Method 2: Web Applications

Use the web application flow if you are building a website that accesses the Leaguevine API. This flow matches the web server application flow from the OAuth 2.0 specification.

At a high level your app/website's login process will go something like this:
  • Your app redirects a user to Leaguevine's OAuth2 login page.
  • The user will enter their credentials, and upon completion, Leaguevine will redirect them back to your app and supply some information in the URL
  • Your app will use that information, along with your app's secret key that we give you when you register to get an access token for that user. You will use this token to interact with Leaguevine on behalf of the user.

Obtain Access Tokens

Instead of asking a user for their credentials, your app will send them to Leaguevine where we will handle the authentication. To obtain an access token to make requests on behalf of a user, simply do the following:
  • Redirect to Leaguevine's login page
    https://www.leaguevine.com/oauth2/authorize/?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &scope=universal
  • If the user accepts, they will be redirected to:
    https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
    This code will be good for 2 minutes. After 2 minutes it will expire and never be usable again.
  • Make a request for an access token
    https://www.leaguevine.com/oauth2/token/?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &code=CODE
    &grant_type=authorization_code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
  • You will get a response that looks like:
    {
    "access_token": "b9c4dde99a", 
    "token_type": "bearer", 
    "expire_in": 157680000, 
    "scope": "universal"
}
    This access_token is good for 5 years, or until the user revokes your access to their profile.

Make Requests

https://api.leaguevine.com/v1/games/234/?access_token=ACCESS_TOKEN

App Login (read only access)

If you would like to make API calls without having a user log in, we support this as well using the OAuth 2.0 Client Credential flow. This flow is extremely simple. However, because no user is logging in, your app will not have permissions to create/modify/delete data on behalf of any users.

If you decide to use this flow to gain an access token, please make efforts to store your client_secret safely.

Obtain an Access Token

Simply make a request to the access_token endpoint using the client_id and client_secret we gave you when you registered your app. 

https://www.leaguevine.com/oauth2/token/?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &grant_type=client_credentials
    &scope=universal
We will supply the access token to you in the body of the response as so: 
{
    "access_token": "0b875eb140", 
    "token_type": "bearer", 
    "expire_in": 157680000, 
}
This access_token is good for 5 years.

Make Requests

https://api.leaguevine.com/v1/games/234/?access_token=ACCESS_TOKEN