¶ Overview

This documentation provides detailed guidance on integrating the Uber OAuth authorization code flow, enabling partners to securely initiate subsequent API calls to Uber services. In addition, we offer a seamless Single Sign-On (SSO) experience via universal links for app-to-app authentication, where applicable.

¶ OAuth Authorization Code Flow via Universal Link

¶ Step 1 - OAuth /authorize request and response

Request Details:

• HTTP Method: GET
• Domain: auth.uber.com
• Path: /oauth/v2/universal/authorize

Query Params	Description
client_id	Your application’s client ID
response_type	Must be set to code for the authorization code flow
redirect_uri	The redirect URI registered for your application
scope	Space-delimited list of requested scopes
state	State value, described in Appendix: State Parameter in OAuth Requests

Example Request from browser:

https://auth.uber.com/oauth/v2/universal/authorize?client_id=<your_client_id>&response_type=code&redirect_uri=<your_client_redirect_uri>&scope=<space-delimited-scope>&state=<your_state>

Note: Make sure to replace the placeholder by the actual value for

• client_id
• redirect_url
• scope
• state

Example Response:

HTTP Status Code 302 Found
Location: <your_client_redirect_uri>?code=<authorization_code>&state=<your_state>

¶ Step 2 - OAuth /token request and response

Request Details:

• HTTP Method: POST
• Domain: auth.uber.com
• Path: /oauth/v2/token
• Content-Type: application/x-www-form-urlencoded (Form Body)

Form Body	Description
client_id	Your application’s client ID
client_secret	Your application’s client secret
redirect_uri	The redirect URI registered for your application
scope	Space-delimited list of requested scopes (optional)
grant_type	Must be set to authorization_code
code	Authorization code returned in Step 1

Example Request:

curl -X POST 'https://auth.uber.com/oauth/v2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'client_secret=<client_secret>' \
  --data-urlencode 'redirect_uri=<partner_redirect_uri>' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=<AUTHORIZATION_CODE_FROM_STEP_1>'

Example Response:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "refresh_token": "<refresh_token>",
  "scope": "offline_access profile profile.mobile_number"
}

_{As the example above, the Uber issued access token lasts 30 days.}

¶ Call Uber Resource API call using the retrieved token from OAuth flow

¶ Get User Profile as the example

Request Details:

• HTTP Method: GET
• Domain: api.uber.com
• Path: /v1.2/me

HTTP Header	Description
Authorization	Bearer <ACCESS_TOKEN_FROM_STEP_2>

Example Request:

curl 'https://api.uber.com/v1.2/me' \
  -H 'Authorization: Bearer <ACCESS_TOKEN_FROM_STEP_2>'

Example Response:

{
  "uuid": "",
  "rider_id": "<unique_uber_user_identifier>",
  "first_name": "<first_name>",
  "last_name": "<last_name>",
  "email": "<email_address>",
  "picture": "<profile_picture_url>",
  "promo_code": "<uber_promo_code>",
  "mobile_verified": <true | false>,
  "mobile_number": "<mobile_number>"
}

_{Note: The uuid field may be empty. Use rider_id as the unique Uber user identifier.}

¶ [For Testing Only] Re-test Uber OAuth Consent Page

In step one, users will be prompted to complete login/signup and consent. Note that the user only needs to consent once for a specific client and the requested scopes. During development, if you want to prompt users to consent again, you can add the additional query param prompt=consent to the /authorize request.

Request Details:

• HTTP Method: GET
• Domain: auth.uber.com
• Path: /oauth/v2/universal/authorize

Additional Query Param	Description
prompt	Set to consent to force showing the consent screen again during development.

Example Request from browser:

https://auth.uber.com/oauth/v2/universal/authorize?client_id=<your_client_id>&response_type=code&redirect_uri=<your_client_redirect_uri>&scope=<space-delimited-scope>&state=<your_state>&prompt=consent

Note: Make sure to replace the placeholder by the actual value for

• client_id
• redirect_url
• scope
• state

¶ Refresh Token Flow

After completing the initial authorization code flow, the response includes both an access token and a refresh token. The access token is valid for 30 days. Once it expires, the refresh token can be used to obtain a new access token without requiring the user to go through the Uber OAuth flow again.

Request Details:

• HTTP Method: POST
• Domain: auth.uber.com
• Path: /oauth/v2/token

Form Body	Description
client_id	Your application’s client ID
client_secret	Your application’s client secret
grant_type	Must be set to refresh_token
refresh_token	Refresh token issued together with access token

Example Request:

curl -X POST 'https://auth.uber.com/oauth/v2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'client_secret=<client_secret>' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=<REFRESH_TOKEN_FROM_STEP_2>'

Example Response:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "refresh_token": "<refresh_token>",
  "scope": "profile profile.mobile_number offline_access"
}

_{Note: The scope value shown is an example.}

¶ Universal Link

¶ Overview

Uber supports universal links to enable both the standard web-based OAuth authorization code flow and an app-to-app single sign-on (SSO) experience for optimized authentication. If an Uber app is installed on the user’s device, the app-to-app SSO flow takes precedence; otherwise, the flow falls back to the web-based experience.

The universal authorization URL is: https://auth.uber.com/oauth/v2/universal/authorize?{params}

¶ User Experience

• Case 1: One Uber App Installed (iOS and Android): Invoking the universal link opens the installed Uber app for authentication and authorization.
• Case 2: No Uber App Installed (iOS and Android): Invoking the universal link opens the default browser for authentication and authorization.
• Case 3: More than One Uber App Installed:
  • iOS: Fallback order: Rides -> Eats -> Postmates -> Driver.
  • Android:
    • Older Versions: Shows a disambiguation dialog asking the user which Uber app to open.
    • Newer Versions: Opens the latest installed Uber app. For example, if the install order is Rides, Eats, Driver, the Driver app will open.

¶ Caveat for Implementation in Android

Please refer to this sample Android app for reference. The launch URI is an Android app link and should be launched using the Android API to get results from an activity: https://developer.android.com/training/basics/intents/result.

// Java
registerForActivityResult(ActivityResultContracts.StartActivityForResult())
// or
activity.startActivityForResult(intent)

App-to-App SSO flow would NOT work if the universal link is invoked using:

// Java
activity.startActivity(intent)

¶ Appendix

¶ State Parameter in OAuth Requests

¶ Overview

The state parameter is a crucial part of the OAuth authorization request. It is used to maintain state between the client’s request and the server’s response. This parameter serves two primary purposes:

1. CSRF Protection: The state parameter helps prevent Cross-Site Request Forgery (CSRF) attacks. By including a unique and unpredictable value in the request, the client can verify that the response received from the authorization server corresponds to the request it originally made.
2. Client State Preservation: The state parameter allows clients to pass back any application-specific data necessary to restore the state. This can include information about the user’s session, the current view, or other context needed to continue the user’s interaction seamlessly after the OAuth flow is complete.

¶ How to Use the state Parameter

1. Generate a Unique Value: Before initiating the OAuth authorization request, generate a unique, random string to use as the state parameter. This value should be unpredictable to ensure security.
2. Include the state Parameter in the Request, i.e.
   https://auth.uber.com/oauth/v2/universal/authorize?{params}
3. Store the state Parameter: Store the state value on the client side, such as in a session or a secure cookie. This storage will be used to validate the response from the authorization server.
4. Validate the state Parameter in the Response: When the authorization server redirects back to your application, it will include the state parameter in the response. Verify that this value matches the one you generated and stored. If the values do not match, the response may be part of a CSRF attack and should be rejected.

¶ References for state

1. https://datatracker.ietf.org/doc/html/rfc6749#section-10.12
2. https://auth0.com/docs/secure/attack-protection/state-parameters#set-and-compare-state-parameter-values