Overview

This document describes the authentication mechanism used by integration partners to access Trac's API. Specifically, it outlines how partners generate and use installation access tokens to authenticate API requests.

Purpose

The installation access token is required to interact with various API endpoints, such as retrieving members, transactions, and products. This authentication process ensures secure access control, preventing unauthorised requests.

Description

Authentication Flow

1. Providing the Public Key

• Integration partners must send their public key to Pebble, which will be used for authentication.

2. Receiving the Installation ID

• Once Pebble has the public key, app and an installation is assigned to the partner. Pebble will then send the installation ID and app slug to the partner.
• A partner may have multiple installation IDs if they integrate multiple systems (e.g., a till integration and a finance integration).

3. Generating a JWT (JSON Web Token)

• Using their public key, partners generate a JWT to authenticate higher-level API requests. You can find more information on this here.

4. Creating an Installation Access Token

• Partners send a POST request to the Create an installation access token for an app endpoint, including:
  • The JWT in the authorization header
  • The installation ID
• Trac responds with an installation access token, which is valid for one hour.

5. Using the Installation Access Token

• The token is required for API requests such as retrieving members or transactions.
• A single token can be reused for multiple requests within its validity period.
• Once expired, a new token must be generated; otherwise, the API will return a 403 Forbidden error.

Authorisation Prefixes

• When creating an installation access token:
  • The JWT must be sent with the Bearer prefix in the authorisation header.
• When making API requests with an installation access token:
  • The token must be sent using the token prefix in the authorization header.
• IMPORTANT NOTE: The above distinction is crucial, as certain API reference documentation may incorrectly specify Bearer instead of token. Partners should always check the credentials section of the API reference (see screenshot below) to confirm the correct prefix.