Lyft

Building Lyft rides into your app

Overview

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 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

Note: Please note that the privileged.* scopes will only be granted if an administrator has approved your client for these permissions. For access to privileged scopes, please email api-support@lyft.com.

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

You will make a request to https://api.lyft.com/oauth/token and provide your Client ID and Client Secret as HTTP Basic Authentication.

Example cURL

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'

Example Response

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":3600,

"scope": "public"

}

Step 2: Use the access token to make requests

When making requests, provide this access token in the Authorization header. The token is valid for multiple requests, but expires after 1 hour. An expired or invalid token will lead to a HTTP 401 response to your request. You can generate a new access token at any time, and you can have multiple valid tokens outstanding.

Example cURL

curl --include -X GET -H 'Authorization: Bearer <access_token>' \

'https://api.lyft.com/v1/eta?lat=37.7833&lng=-122.4167'

Example error response

HTTP/1.1 401 Unauthorized

WWW-Authenticate: Bearer realm=lyft-public-api”

error: {invalid_token|token_expired|insufficient_scope}

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.

GET 'https://api.lyft.com/oauth/authorize'

Field name 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 payload which will be passed back to your application through the redirect

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. The authorization code should be used in the next step. It is a one-time use code, which expires after 10 minutes.

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

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.

Example cURL

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'

Example Request

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>"

}

Example Response

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 the access token can now use the access token returned by the Lyft API. 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.

Example cURL

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'

Example Request

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>}

Example Response

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.

POST 'https://api.lyft.com/oauth/revoke_refresh_token'

Example cURL

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'

Example Response

HTTP/1.1 200 OK

Cache-Control: no-store

Content-Type: application/json

Pragma: no-cache

Content-Length: 22

Connection: keep-alive

Authentication Errors

Example Error Response

HTTP/1.1 401 UNAUTHORIZED

Cache-Control: no-store

Content-Type: application/json;charset=UTF-8

Pragma: no-cache

WWW-Authenticate: Basic realm="lyft-public-api"

Content-Length: 72

Connection: keep-alive

{

"error": ,

"error_description":

}

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 invalid_client unauthorized client