Register an OAuth simple client (custom) app

In order to make any call to the Apaleo Identity API, and to request your OAuth 2.0 access token, you need to register a client application. Registered OAuth applications are assigned a unique Client ID (client_id) and a unique Client Secret (client_secret). Make sure to store the Client Secret securely.

Only users with administration management privileges can register applications.

To register OAuth simple client app:

  1. Log into the Apaleo Dashboard with your Apaleo developer credentials. If you don’t have an account, sign up for your Apaleo developer account.

  2. Navigate to the Apps section and click Connected apps.

  3. On the connect clients page, click Add a new app.

  4. On the Add a new app dialog, select Add custom app.

  5. On the New custom app page, enter the following details:

    Field Description
    Client code A short, unique key for the app. Make it clearly describe what the app is for (its mission), for example the data export it runs, so anyone who sees it can tell what it does. It becomes part of your client ID. Use 3 to 30 characters: letters, numbers and underscores only. Letters are capitalised automatically.
    Client name A human-readable name that states what the app is for. Describe the app’s mission, for example “Nightly accounting export”, and not a technical name. You and other admins see this name in the list of connected apps.
    Personally identifiable information Decide which personal guest data your app receives: Retrieve, Omit linked or Omit all. This can’t be changed after the app is created. See Personal data (PII) below.
    Secrets Description of your secret. You can add a new secret to your app to get a new client secret if you believe that the existing client secret has been compromised.
    Client access Defines how your app’s access is granted. This can’t be changed after the app is created. Choose Fine-grained client (recommended): least-privilege access, where you grant only the exact permissions your app needs, per API. Or choose Scope client: broad API scopes bundled into the OAuth token.
    Scopes The OAuth scopes your app needs. Scopes let you specify how your app needs to access an Apaleo user’s account. Scope clients only.
    Permissions The exact permissions your app needs, per API. The same permissions apply to all customer selected properties. Fine-grained clients only.
    Property access Select which properties your app can access: All properties (applies to all current and future properties of this account) or Only selected properties (select at least one property). The properties and permissions you select here define what your app can access with its credentials. Fine-grained clients only.

    This is how the Client access section looks:

    To find out which scope or permission an operation requires, see Scopes and permissions.

  6. Review your app details and save your app.

  7. Take note of the client ID and client secret. You’ll need these in the next step to initiate the OAuth flow.

    • Client ID - This identifies the client responsible for the OAuth request. A unique key for the client application.
    • Client Secret - A client secret is a secret known only to your application and the authorization server. It protects your resources by only granting tokens to authorized requestors. Always store the client secret key securely; never reveal it publicly! If you suspect that the secret key has been compromised, regenerate it immediately by adding a new secret to the client application.

Personal data (PII)

Your app works with the personal data of hotel guests, so think about which data it really needs before you register it. You choose one of three options for Personally identifiable information, and this can’t be changed after the app is created. If you need different data later, you have to register a new app. The form shows a preview of the guest data for each option, so check them before you decide.

  • Retrieve: your app receives all personal information of the guest, such as name, email, phone number, address, identification and birth date.
  • Omit linked: personal data that directly identifies a guest is left out or masked, for example first name, email, phone, birth date and identification number. Details such as title, country, city and language remain.
  • Omit all: your app receives no personal guest data at all: no names, phone numbers, email addresses and so on.

Choose the most restrictive option that still lets your app do its job. A reporting or accounting app, for example, often doesn’t need names or contact details. Retrieve is preselected on the form, so choose on purpose and don’t just accept the default.

Changing your app later

You can edit your app at any time, for example to change its scopes or permissions.

The client access type can’t be changed. If you need a different type, register a new app.

Deleting your app

OAuth custom client apps can be deleted from your account. Click on 3 dots - “Delete”.