Authentication

There are two ways to authenticate with Hook0's API: using a JWT or using an application secret.

Both token are to be included in HTTP requests using a header:

Authorization: Bearer [token]

TL;DR

• JWTs are used by Hook0 UI and let you interact with the whole API as a human user
• Application secrets allow any program to interact with the API but only for a given Hook0 application

When sending events from you application to Hook0, you should use an application secret!

JWT

JWTs are emitted by the Keycloak instance that is connected to Hook0. Hook0 relies on Keycloak to handle users, login flows, …

When you are logging into Hook0 UI, you are actually logging into Keycloak, which then gives a JWT to your web browser so that Hook0 UI uses it to communicate with Hook0's API.

This JWT allows you to use the whole API. Of course, you can only interact with the organizations your user have access to, according to the roles you have.

The main drawback of using JWT is that you need to use the login web page and renew your access token very often (using a refresh token provided by Keycloak).

📘

This makes it a good authentication method for humans or one-off scripts.

Application secret

Application secrets are created by you, through Hook0's UI or API.

They are simple Bearer tokens stored in Hook0's database.

The can be used to interact with the API, but as they are linked to applications, they can only be used with endpoints that are related to an applications. For example, you cannot create an application or list every application that belong to your organization. But you can list and edit event types or subscriptions, as long as your requests are targeting the same application your application secret belongs to.

Application secrets are somewhat very similar to GitHub's or GitLab's deploy keys: they are linked to a repo (≅ an Hook0 application) and not to any user.

📘

This makes it a good authentication method for programs that interact with a given Hook0 application.