OAuth 2.0 - Client credentials grant flow

In the client credentials flow, the Authorization Server provides an access token directly to the client app after verifying the client app’s client ID and client secret. The client credentials grant type is the least secure grant type. Therefore, it is only recommended for internal client apps highly trusted by the resource server (for example, when the client app and the resource server are part of the same account (hotel organization)).

In contrast to the other OAuth flows used to obtain access tokens, this flow does not require a user login and the client does not redirect a user’s web browser to a username/password login process. The client app acts on its own behalf and assumes the role of the resource owner.

You must only use this flow if you trust the client. In other words, if the client is a computer that your hotel owns, then it will be secure and you can ensure the safety of the client credentials. Public clients can’t be trusted to identify themselves using client authentication, so that would not be a good candidate for client credentials grant flow.

The following image shows an outline of the flow:

App (Client)
    │
    │  1. Authenticate with client ID and secret
    │     to request an access token
    ├──────────────────────▶ Apaleo Identity API (Authorization Server)
    │
    │  2. Provide an access token
    │◀────────────────────── Apaleo Identity API (Authorization Server)
    │
    │  3. Authenticate with the access token to request data
    │     from the resource server
    ├──────────────────────▶ Apaleo Resource APIs (Resource Server)
    │
    │  4. Provide the requested data
    │◀────────────────────── Apaleo Resource APIs (Resource Server)
    ▼

Client credentials grant provides the following endpoint:

Why we recommend the connect clients?

Normally we recommend you to use the connect flow in order to communicate with the Apaleo APIs because when you use simple clients, you would need to create new client credentials per each hotel that you want to target with your application. This means that for every hotel account that you want to integrate with your application, you would need to request new credentials following the steps below.

You can limit what a simple client can access. A custom app is created in the Apaleo account it is used with. If you register it as a fine-grained client, you choose which properties it can access and which permissions it has when you create the app. It can’t access anything else, so it no longer has to see every property in the account. You still need separate credentials for each Apaleo account. See Register an OAuth simple client (custom) app.

This is a limitation that disappears with the connect clients, as you will only need for the account admin to authorize your application, and you would get access to the properties they choose to grant. This means that you basically have access to all accounts with a single set of credentials.

Additionally, connect clients are also very simple to integrate. If you want to learn more about connect clients, go to OAuth 2.0: Authorization code flow.

However, if you are completely sure, that the simple client is the way to go for you. Just follow the following steps and you should be all set.

Step 1. Client requests an access token

Step 2. Start making REST API calls

Prerequisites

Create a client app and get client credentials

After creating the Apaleo developer account, the next step of creating an app is to register the OAuth simple client (custom) app in Apaleo.

The registration process involves entering basic client app details and the access that your app needs for the endpoints that you want to access: scopes for a scope client, or permissions and properties for a fine-grained client. The client access type can’t be changed after the app is created.

If desired, you can edit the rest of a registered client app at any point in the future. The registration process is not considered as a part of the authorization flow

To learn how to create your client, go to Register the OAuth simple client (custom) app.

Step 1. Client requests an access token

You can obtain an access token by making a POST request to the token endpoint with required parameters. Combine your client id and secret into a string, separated by colon, it would look something like yourClientId:YourClientSecret and encode that string with Base64. This will result in one long string, similar to the one you see below:

eW91ckNsaWVudElkOllvdXJDbGllbnRTZWNyZXQ=

Now that you have your client credentials in a Base64 string, it is time to request your access token. In order to do that make a request to the https://identity.apaleo.com/connect/token, endpoint.

This endpoint supports the following headers:

This endpoint supports the following parameters:

POST https://identity.apaleo.com/connect/token
Authorization: Basic <base64 encoded "clientId:clientSecret">
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

Example cURL request

You can test the creation of token by running the following cURL command.

On Windows, use Windows Subsystem for Linux (WSL) to run the cURL command.

curl -X POST 'https://identity.apaleo.com/connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic U0RYRS1TNWUFQ......UZHWHZaRm1wc1labTc=' \
  -d 'grant_type=client_credentials'

The authorization server returns a JSON-formatted response when your request succeeds. If the example request above succeeds, the server returns a response like this:

{
  "access_token": "eyJhbGci............6XUKmNJyyNRA",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "availability.read companies.read identity:account-users.manage identity:account-users.read offers.read reservations.manage reservations.read"
}

The example above is for a scope client. For a fine-grained client, scope contains only the marker scope identity:permissions. The app’s access is defined by the permissions and properties you selected when you created it, not by this field. Don’t infer API access from scope; check the client’s configured permissions instead.

The JWT looks like this:

{
  "nbf": 1591448890,
  "exp": 1591452490,
  "iss": "https://identity.apaleo.com",
  "aud": ["api", "identity_server", "notifications", "apaleo"],
  "client_id": "SDXE-SP-SIMPLEAPP",
  "account_code": "SDXE",
  "scope": [
    "availability.read",
    "companies.read",
    "offers.read",
    "reservations.manage",
    "reservations.read",
    "identity:account-users.manage",
    "identity:account-users.read"
  ]
}

For a fine-grained client, the scope claim contains only the marker scope identity:permissions, and aud also lists the extra APIs a fine-grained client can reach: integration, fiscalization, profile, rendering, distribution, scheduler, config and payment. The other claims are the usual ones (account_code, client_id).

The client app can make subsequent requests to the protected resource APIs until the access token received from the Authorization Server expires, in which case the process repeats.

Step 2. Start making REST API calls

Once the access_token has been obtained, it can be used to make calls to the protected resource APIs by passing it as a Bearer Token in the Authorization header of the HTTP request.

This sample call, which shows details of a property, includes a bearer token in the Authorization request header. This type of token lets you complete an action on behalf of a resource owner.

GET https://api.apaleo.com/inventory/v1/properties/MUC
Content-Type: application/json
Authorization: Bearer my-authentication-token

Example cURL request

You can test your token by running the following cURL command.

On Windows, use Windows Subsystem for Linux (WSL) to run the cURL command.

curl -i -H 'Authorization: Bearer eyJhbGci............6XUKmNJyyNRA' -X GET https://api.apaleo.com/inventory/v1/properties/MUC

The response shows the property details:

{
  "id": "MUC",
  "code": "MUC",
  "isTemplate": false,
  "name": {
    "en": "Hotel Munich"
  },
  "description": {
    "en": "This new cozy hotel is located in the heart of Schwabing and is walking distance from the historical city center."
  },
  "companyName": "Hotel München GmbH",
  "commercialRegisterEntry": "Amtsgericht München, HRB 145673183",
  "taxId": "DE311053702",
  "location": {
    "addressLine1": "Leopoldstraße 8-10",
    "postalCode": "80802",
    "city": "Munich",
    "countryCode": "DE"
  },
  "bankAccount": {
    "iban": "DE44 5001 0517 5407 3249 31",
    "bic": "SSKMDEMMXXX",
    "bank": "Stadtsparkasse München"
  },
  "paymentTerms": {
    "de": "Zahlbar bei Check In",
    "en": "Payment on check-in"
  },
  "timeZone": "Europe/Berlin",
  "currencyCode": "EUR",
  "created": "2020-04-08T21:53:26+02:00"
}

403 Forbidden. With a fine-grained client, the API responds with 403 Forbidden if your app lacks the permission an endpoint requires, or if the request is about a property your app hasn’t been granted access to. Your access token itself is still valid. To see which scope or permission an operation requires, see Scopes and permissions.