Getting started with OAuth 2.0¶

What does it do?¶

OAuth 2.0 is the industry standard protocol for authorization.

Why use it?¶

As our Public API returns private data, communication between the Booking.com Taxi Public API and our supply partner APIs must be secure. Without implementing the OAuth 2.0 authentication flow in your API, you won't be able to consume our Public API.

How does it work?¶

The API is secured using the OAuth 2.0 standard with the client credentials flow. When you sign up to use the API a Client ID and Client Secret will be issued. These credentials are used in a two-step process:

Get a token — Call the token endpoint using Basic authentication (Base64(clientId:clientSecret))
Call the API — Use the returned JWT token in the Authorization header for all subsequent API requests

Warning

It's important your Client ID & Client Secret keys remain private and are not shared.

Credentials¶

Credential	Description	Requirements
Client ID	A unique identifier for your integration, provided by your account manager.	Min length 1, max length 128.
Client Secret	A cryptographically secure secret, provided by your account manager. Must be kept confidential.	Min length 1, max length 64.

Step 1: Retrieve a token¶

Exchange your Client ID and Client Secret for a short-lived JWT token by calling the Cognito token endpoint.

The Authorization header must be Basic followed by the Base64-encoded value of clientId:clientSecret.

curl -X POST \
  --user '<CLIENT_ID>:<CLIENT_SECRET>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://dispatchapi-sandbox-qa.auth.eu-west-1.amazoncognito.com/oauth2/token?grant_type=client_credentials'

See the token endpoint reference for full request and response details.

Step 2: Authenticate API requests¶

Once you have a token, include it in the Authorization header when calling any API endpoint.

Headers¶

Header	Value	Description
Authorization	`<JWT_TOKEN>`	The JWT token retrieved from Step 1
Content-Type	application/json	Required for all requests

curl -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <JWT_TOKEN>' \
  'https://dispatch-api-sandbox.qa.someonedrive.me/v1/bookings'

Note

The examples above use the sandbox URL. Your account manager will provide production credentials and URLs.

Token expiry¶

Tokens are short-lived. When a token expires, you will receive an HTTP 401 Unauthorized response. When this happens, request a new token from the Cognito endpoint and retry the request.