Signed search

You can use signed search to build out the customer facing parts of your app, without exposing your app API key. By generating a signed search request, you can securely scope the query to a single customer.

👍

Dive deeper 🤓

You can learn more about what signed search is and what it can be used for in the documentation.

The token needed to sign the request is generated using JWT. If you have no idea what JWT is, please have a look here to learn more. The token never expires, so you can generate it once and store it in your database.

Usually you will use a library to generate the JWT token, depending on which programming language you are using. When generating a token for a signed request, you need to provide 2 things in the payload: An app slug and the data identifying the user (customer.email or meta.something). It looks like this:

{
  "app_slug": "my-app-6165",
  "customer.email": "[email protected]"
}

Or using meta data:

{
  "app_slug": "my-app-6165",
  "meta.customer_id": "12345"
}

When you have generated your token, you can use it like this:

https://api.timekit.io/v2/bookings?search=customer.email:[email protected]&signed_search={JWT_TOKEN}

If someone tries to tamper with the URL and try to change the email, the JWT token will be invalidated and the request will fail.

You are welcome to add more search params to the query, as long as the signed part still matches for the customer:

https://api.timekit.io/v2/bookings?search=customer.email:[email protected];state:confirmed&signed_search={JWT_TOKEN}

Remember that you only need to generate the token once. It never expires as long as the way you identify the customer doesn't change.