Migration
This document describes how to continue to provide rides to your customers by integrating with the Ride Request API. Depending on which endpoints you’re currently using, you may need to perform some migration work.
Follow the steps for the section that describes your use case:
- Migration Work: Switch to OAuth Bearer Token
- Migration Work: Switch to new versions, scopes, and deep links
¶ Migration Work: Switch to OAuth Bearer Token
Your current use requires you to pass in a header with the key “Authorization” and value “Token <TOKEN>”, where <TOKEN> is the OAuth Server Token that you acquired from your application’s Developer Dashboard page. Server tokens are being completely deprecated and this method of authorization will no longer work.
Instead, you will need to generate and store an OAuth Bearer Token with the right OAuth Scopes associated with it. The scope associated with the four endpoints above is a bearer access token of type Client Credentials Grant. This means that a user is not required to be logged in to grant permission to your application through a consent flow. The four endpoints above are used for Uber time and price estimates, and for available Uber products in a given location, and thus do not contain any user PII. Real-time requests made with this type of access token should be very similar to your application’s current traffic with a server token.
To generate an OAuth Bearer Token of type Client Credentials Grant, follow these steps.
¶ Generate a Client Credentials Token
To generate a client credentials token, retrieve your client_id and client_secret for your app from the Developer Dashboard and see the example below.
¶ Reference
Key | Value |
---|---|
url | https://auth.uber.com/oauth/v2/token |
scope | Space delimited list of scope(s) that you would like to generate a token for. |
grant_type | Based on scope(s). Either client_credentials for an application generated token (to access Store, Menu, Order, and Reporting endpoints) or authorization_code for a user access token (to access POS Provision endpoints). |
¶ Generate a Client Credentials Token
To generate a client credentials token, retrieve your client_id and client_secret for your app from the Developer Dashboard and see the example below.
¶ Example Request
curl -F "client_secret=$CLIENT_SECRET" \
-F "client_id=$CLIENT_ID" \
-F "grant_type=client_credentials" \
-F "scope=ride_request.estimate" \
https://auth.uber.com/oauth/v2/token
¶ Example Response
{
"last_authenticated": 0,
"access_token": "KA.ewogICJ2ZXJzaW9uIjogMiwKICAiaWQiOiAiZmFuY3kgc2VlaW5nIHlvdSBoZXJlLCBodHRwOi8vdC51YmVyLmNvbS9123412413123123sCiAgImV4cGlyZXNfYXQiOiAxNDk3NzQxNjIyLAogICJwaXBlbGluZV9rZXl123123123123faWQiOiAiZm9vYmFyIiwKICAicGlwZWxpbmVfaWQiOiAxCn0K.9jPtNyS9vHJ9HVmxA4Y6vwIcwv7v1tx1BMYwztpIeID",
"expires_in": 2592000,
"token_type": "Bearer",
"scope": "ride_request.estimate",
"refresh_token": ""
}
¶ Usage
The access_token field will contain the token used to authenticate against the Uber API. Once you’ve obtained this token, you can provide it in the “Authorization” header of requests you make to endpoints that require client credentials scopes.
The expires_in field indicates the lifetime of the access token, provided in seconds. Tokens are valid for 30 days (2,592,000 seconds) and should be cached and re-used across requests until (or shortly before) expiration, not re-generated per request.
curl -H 'authorization: Bearer <TOKEN>' \
https://api.uber.com/v1.2/requests/estimates/price
As mentioned above, the access token expires in 30 days. You cannot request an expiry time beyond that of the maximum value of 30 days. You can regenerate your access token anytime before the expiry (e.g. it could be on day 25, or on day 29).
You will need a mechanism to GENERATE the access token ONCE for your integration as an offline mechanism, then STORE this access token on your servers, and finally USE it for all subsequent requests in the same way that you do with server tokens today.
The only difference for real-time requests would be the value of the header. The header will use the key “Authorization” as before, and the value be of the format “Bearer <TOKEN>” where <TOKEN> is the OAuth Bearer Token that was generated and stored on your servers.
¶ Migration Work: Switch to new versions, scopes, and deep links
There are three sub-changes:
- The OAuth Scopes required to access the Ride Request API have changed.
- Older versions of certain endpoints are being deprecated in favor of either an updated version (noted with v1.2) or with a deep link alternative.
- Certain endpoints are being completely deprecated.
For sub-changes 1 and 2, please refer to the table below for new scope requirements and for updated version URLs that your integration needs to switch to. In the case of deep link alternatives, please redirect your users by deep-linking them to the Uber mobile app.
(Current) Endpoint Path | Updated Scope Requirements | Migrate to |
---|---|---|
GET /v1/estimates/price | ride_request.estimate | GET /v1.2/estimates/price |
GET /v1/estimates/time | ride_request.estimate | GET /v1.2/estimates/time |
GET /v1/products | ride_request.estimate | GET /v1.2/products |
GET /v1/products/{} | ride_request.estimate | GET /v1.2/products/{} |
DELETE /v1/requests/current | ride_request.ride_booking | DELETE /v1.2/requests/current |
DELETE /v1/requests/{} | ride_request.ride_booking | DELETE /v1.2/requests/{} |
GET /v1/requests/current | ride_request.ride_booking | GET /v1.2/requests/current |
GET /v1/requests/{} | ride_request.ride_booking | GET /v1.2/requests/{} |
PATCH /v1/requests/current | ride_request.ride_booking | PATCH /v1.2/requests/current |
PATCH /v1/requests/{} | ride_request.ride_booking | PATCH /v1.2/requests/{} |
POST /v1/requests | ride_request.ride_booking | POST /v1.2/requests |
POST /v1/requests/estimate | ride_request.ride_booking | POST /v1.2/requests/estimate |
DELETE /v1/payment-methods/{} | uber://payments/manage (Deep Link) | |
GET /v1/payment-methods | ride_request.user_payment_methods | GET /v1.2/payment-methods |
GET /v1/payment-methods/{} | uber://payments/manage | |
GET /v1/places/{} | ride_request.place | GET /v1.2/places/{} |
PATCH /v1/payment-methods/{} | uber://payments/manage (Deep Link) | |
POST /v1/payment-methods | uber://payments/manage (Deep Link) | |
PUT /v1/places/{} | ride_request.place | PUT /v1.2/places/{} |
GET /v1.1/history | ride_request.user_history | GET /v1.2/history |
DELETE /v1.2/requests/current | ride_request.ride_booking | no-change |
DELETE /v1.2/requests/{} | ride_request.ride_booking | no-change |
GET /v1.2/requests/current | ride_request.ride_booking | no-change |
GET /v1.2/requests/{} | ride_request.ride_booking | no-change |
GET /v1.2/requests/{}/map | deprecated functionality | |
GET /v1.2/requests/{}/receipt | uber://trips (Deep Link) | |
PATCH /v1.2/requests/current | ride_request.ride_booking | no-change |
PATCH /v1.2/requests/{} | ride_request.ride_booking | no-change |
POST /v1.2/requests | ride_request.ride_booking | no-change |
POST /v1.2/requests/estimate | ride_request.ride_booking | no-change |
DELETE /v1.2/payment-methods/{} | uber://payments/manage (Deep Link) | |
GET /v1.2/history | ride_request.user_history | no-change |
GET /v1.2/payment-methods | ride_request.user_payment_methods | no-change |
GET /v1.2/payment-methods/{} | uber://payments/manage (Deep Link) | |
GET /v1.2/places/{} | ride_request.place | no-change |
PATCH /v1.2/payment-methods/{} | uber://payments/manage (Deep Link) | |
POST /v1.2/payment-methods | uber://payments/manage (Deep Link) | |
PUT /v1.2/places/{} | ride_request.place | no-change |
GET /v1.2/estimates/price | ride_request.estimate | no-change |
GET /v1.2/estimates/time | ride_request.estimate | no-change |
GET /v1.2/products | ride_request.estimate | no-change |
GET /v1.2/products/{} | ride_request.estimate | no-change |
GET /v1/requests/{}/receipt | uber://trips (Deep Link) | |
GET /v1/me | no-change | |
GET /v1.2/me | no-change |
Some of these have public documentation available on https://developer.uber.com/docs/riders
For sub-change 3, note the following endpoints that are being deprecated with no available alternative.
Endpoint Path |
---|
GET /v1/requests/{}/map |
GET /v1/sandbox/map |
PUT /v1/sandbox/products/{} |
PUT /v1/sandbox/requests/{} |
GET /v1/me/promotions |
GET /v1/promotions |
GET /v1.2/me/promotions |
GET /v1.2/promotions |
GET /surge-confirmations/{} |
POST /surge-confirmations/{} |
GET /v1.2/sandbox/map |
PUT /v1.2/sandbox/products/{} |
PUT /v1.2/sandbox/requests/{} |
PATCH /v1/me |
PATCH /v1.2/me |