Lyft

Lyft's API

Drive your app to success with Lyft's developer API. You'll find comprehensive guides and documentation to help you start working with Lyft as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Authentication

OAuth2

The Lyft API uses OAuth2 over SSL for authentication and authorization. You may find this straightforward if you've worked with OAuth2 before.

Access tokens

To use the Lyft API, your app must send an OAuth2 access token in an Authorization header with each request. There are two ways of retrieving access tokens.

If you are accessing endpoints that are not user-specific (eg. ETA, cost, ride types) you will go through a "2-legged" flow.

If you are requesting access to a Lyft user's account in order to make requests on their behalf, you will go through a "3-legged" flow.

Scopes

You'll need to include a list of requested scopes during the OAuth flow. When using the 3-legged flow, users will be asked to grant permission to your application's requested scopes when they authenticate.

Scope Access Description
public default grants access to the ride types, ETAs, and cost endpoints
rides.read default grants access to the user's current and past ride information
offline optional required in order to get access to a refresh_token
rides.request optional for requesting and managing a passenger's rides
profile optional for requesting profile information about a user

Client Credentials (2-legged) flow for public endpoints

The tokens granted here are valid for endpoints that don't require access to user data. (eg ETA, cost, ride types)

Step 1: Obtain an access token

First, make a request to https://api.lyft.com/oauth/token and provide your client_id and client_secret as the username:password through HTTP Basic Authentication.

curl -X POST -H "Content-Type: application/json" \
     --user "<client_id>:<client_secret>" \
     -d '{"grant_type": "client_credentials", "scope": "public"}' \
     'https://api.lyft.com/oauth/token'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "token_type":"Bearer",
   "access_token": <access_token>,
   "expires_in":86400,
   "scope": "public"
}

Step 2: Use the access token to make requests

When making requests, provide the returned access_token in the Authorization header, in the form Authorization: Bearer <access_token> . The token is valid for multiple requests, but expires after 1 day.

In this example, we're querying the Driver ETA endpoint:

curl --include -X GET -H 'Authorization: Bearer <access_token>' \
     'https://api.lyft.com/v1/eta?lat=37.7833&lng=-122.4167'

An expired or invalid token will lead to a HTTP 401 response to your request, which might look like:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="lyft-public-api"
error: {invalid_token|token_expired|insufficient_scope}

You can generate a new access token at any time, and you can have multiple valid tokens outstanding.

3-Legged flow for accessing user-specific endpoints

To make ride requests or otherwise access user data, the user must grant you access. Users who don't have a Lyft account will be prompted to create a new account if they are directed through the following flow.

Step 1: Obtaining access to the user's Lyft account

First, direct the user to the following URL (hosted by Lyft) with query parameters set appropriately for your application. The user will see information about your application, along with the list of permissions your application is requesting. The user can indicate whether Lyft should grant access to your application or not.

Parameter Description
client_id your application's client ID
response_type at this time, the only supported value is code
scope the space-delimited list of scopes which your application is requesting
state a value returned as a parameter along with the authorization code. It can be used to maintain state during the redirection process and should be used to prevent cross-site request forgery (see the OAuth 2.0 RFC Section 10.12)
# This request should originate from the logged-in user
curl -X GET 'https://www.lyft.com/oauth/authorize?client_id=<client_id>&scope=public%20profile%20rides.read%20rides.request%20offline&state=<state_string>&response_type=code'

Step 2: Handling the redirect

If the Lyft user grants your application access to the requested permissions, Lyft will issue a 302 redirect to the Redirect URI you've set up with Lyft, along with an authorization code as a URL parameter. The authorization code should be used in the next step. It is a one-time use code, which expires after 10 minutes. It will appear on your server like this:

GET 'your-redirect-uri/?code=<authorization_code>'

If you need help debugging the response to your server, consider making a test application and configuring the Redirect URI as http://localhost or using a service for testing webhooks.

Step 3: Retrieving an access token

Your server should retrieve a one-time-use authorization_code and pass it to Lyft in order to retrieve an access token. The access token will enable you to make requests on behalf of the Lyft user. Remember to include your application's client_id and client_secret as the username:password through HTTP Basic Auth when issuing a POST, as demonstrated below.

# This request comes from your server
curl -X POST -H "Content-Type: application/json" \
     --user "<client_id>:<client_secret>" \
     -d '{"grant_type": "authorization_code", "code": "<authorization_code>"}' \
     'https://api.lyft.com/oauth/token'
POST /oauth/token HTTP/1.1
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json;charset=UTF-8

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": <access_token>,
  "refresh_token": <refresh_token>,
  "token_type":"bearer",
  "expires_in":3600,
  "scope": "space delimited string of scopes"
}

Step 4: Use the access token

API requests which require access tokens can now use the access_token returned from Step 3. Just like the 2-legged flow, when making requests you'd provide this access_token in the Authorization header. But unlike the 2-legged flow, you can now leverage user-specific API endpoints, like the Users - Ride History example below:

curl -X GET -H "Authorization: Bearer <access_token>" \
     'https://api.lyft.com/v1/rides?start_time=2015-12-01T21:04:22Z&end_time=2015-12-04T21:04:22Z&limit=10'

The access token expires after 60 minutes, so you will need to refresh the tokens thereafter.

Step 5: Refreshing the access token

When the user's access token has expired, you may obtain a new access token by passing the refresh_token returned above. As with all POSTs in the 3-legged flow, remember to include your application's client_id and client_secret as the username:password through HTTP Basic Auth.

curl -X POST -H "Content-Type: application/json" \
     --user "<client_id>:<client_secret>" \
     -d '{"grant_type": "refresh_token", "refresh_token": <refresh_token>}' \
     'https://api.lyft.com/oauth/token'
POST /oauth/token HTTP/1.1
Host: api.lyft.com
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
Cache-Control: no-cache
Postman-Token: 4ad87aed-b46d-76a7-d765-4c0aa38e2fef

{"grant_type": "refresh_token", "refresh_token": <refresh_token>}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": <access_token>,
  "token_type":"bearer",
  "expires_in":3600,
  "scope": "space delimited string of scopes"
}

Step 6: Revoking the access token

If your application no longer needs access to the user's account, you can revoke the access token by passing it to the /oauth/revoke_refresh_token endpoint, including your client_id:client_secret through HTTP Basic Auth. As demonstrated below, we expect the access token you're revoking as JSON data in the body of the request.

curl --include -X POST -u '<client_id>:<client_secret>' \
     -H 'Content-Type: application/json' \
     --data '{"token": <refresh_token>}' \
     'https://api.lyft.com/oauth/revoke_refresh_token'
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Pragma: no-cache
Content-Length: 22
Connection: keep-alive

HTTP Status Codes

HTTP Status Code
Error Type
Description

400

invalid_request

could not find or parse grant_type, did you set the Content-Type header correctly?

400

unsupported_grant_type

grant_type must be client_credentials, authorization_code, refresh_token

401

N/A

A 401 status code with a an empty body indicates that your access token has expired. You can use your refresh token to request a new one.

Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.