Partner Authentication using API keys

Introduction

This guide is intended for partners who are developing integrations intended to be used by all Pleo customers.

Why use API keys?

While OAuth2 is the Pleo preferred way of authenticating external applications, since it provides our users with a better installation experience while also providing a more secure way of authenticating, there are cases where API keys are necessary. Such as:

Legacy systems that can't be updated to use OAuth2
On-premise systems that can't use OAuth2 due to network restrictions

Working with API keys during development

There are two ways to obtain an API key during the development phase:

Via your partner manager after your sandbox account is created.
Via the in-product experience

These keys can be used to test and validate authentication and authorization when building against the Pleo API

Customer experience for Creating a new API key

To ensure that the API key is created with the permission set relevant to the integration, customers can generate an API during the integration installation process

In the Pleo web app, user selects an application to install.
The user finds the app they want to install, can click on the "Connect" button.
If installation connects using API Keys, a modal will appear, where the user will see which permissions the app will need
Once the user allows and confirms with their passcode, the API key will be generated, which can then be copied to the clipboard.

❗️Important notice:

It's important to note that this is the only time the key is shown, so the user should store it securely.

Authenticating with API keys

When authenticating with API keys, the user will have to include the key in the Authorization header of the request, using the Basic schema. The key should be used as the username, and an empty string should be used as the password.

Curl example:

With curl, you can simply specify the -u / --user flag, followed by the API key. The password is an empty string.

curl --request GET -sL \
     --url 'https://external.pleo.io/v1/installations/me'\
     -u 'API_KEY'

Postman example:

In Postman, you can specify the API key in the Authorization tab, selecting the Basic Auth type, and using the API key as the username, and an empty string as the password.

Creating an installation

For 3rd party developered applications offered to all Pleo cusyomers, it is expected that the application will create its own installation of the app. This is to ensure that the integration's status can be properly reflected in the Pleo context.

This can be achieved by using the POST /v1/installations/me endpoint. The installation will be associated with the API key, and information about the application and subject will be derived from the API key.