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 secret will be issued. The credentials must remain private and should not be shared. Your client ID and secret can be used to retrieve a token which is then used to authenticate requests to the Public API endpoints. The tokens are short-lived and should be updated when they expire by calling the authentication service again.
Once on-boarded a Client ID and Client Secret will be provided to you. It's important the keys remain private and are not shared. The authentication endpoint can be called to exchange the keys with an access token which is then used to authenticate each subsequent request.
Warning
It's important your Client ID & Client Secret keys remain private and are not shared.
| Credential | Description | Requirements | Example |
|---|---|---|---|
| Client ID | The client ID is considered public information. Even though it’s public, it’s best that it isn’t guessable by third parties, so you should generate something like a 32-character hex string. | Minimum length of 1. | Maximum length of 128. |
| Client Secret | It must be sufficiently random to not be guessable, which means you should avoid using common UUID libraries which often take into account the timestamp or MAC address of the server generating it. A great way to generate a secure secret is to use a cryptographically-secure library to generate a 256-bit value and converting it to a hexadecimal representation. | Minimum length of 1. | Maximum length of 64. |
Authenticating with a token¶
Once you've exchanged your client ID & client secret for a token, you can use it when calling our API endpoints by including the token in the Authorization header.
Headers¶
| Header | Value |
|---|---|
| Authorization | Basic <token> |
| Content-Type | application/json |
Sample CURL Requests¶
Note
The examples below show our sandbox URL.
Exchange your client ID & client secret for a token:
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'
Call the bookings endpoint with the retrieved token:
curl -X GET -H 'Content-Type: application/json' -H 'Authorization: <JWT_TOKEN>' https://dispatch-api-sandbox.qa.someonedrive.me/v1/bookings