Integrating with Pebble, and others

We have a range of financial systems on offer - Tali, Till and now Trac.

Trac is our integration product, providing a highly performant, highly reliable API designed specifically to suit the needs of a variety of business sectors, to enable them to integrate with us and with others.

In this documentation site you will soon find everything you need to get started as an integrator. This is a work in progress, so do please also join our Slack where we'll be happy to help you.

Writing an integration

To write an integration with Trac you will need to:

Create a public/private keypair for your test integration. This is used for the JWT/RSA authentication described below.
Send us the public key, requesting access to the test api endpoint.
We will register your integration as a "Trac App", and provide you access to some test organisations.

You will then be able to code against the test API.

When you wish to enter production you will need to produce a new production key pair and be authorised for production access. This will require approval for your integration by Pebble.

Note that access to the APIs may be rate limited and you must be able to accommodate rate limiting.

Authenticating your integration

Endpoints in the Trac API are authenticated using two methods, signed JWTs and by the use of Bearer tokens. Signed JWTs are used to acquire the bearer tokens used to access the rest of the API.

Signed JSON Web Tokens (JWT)

You can read more about JWTs at https://jwt.io.

The endpoints under /apps all require signed JWTs for access. You will need to contact us to provide your public key to gain access to the test or production APIs.

Generating your RSA public and private keys

openssl genrsa -out mykey.pem 4096
openssl rsa -in mykey.pem -pubout -out pubkey.pem

Using your JWT

Once your integration has been accepted and registered you can access the /apps endpoints using the Authorization header:

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/json" https://trac.mypebble.co.uk/api/v1/apps

Installation in an organisation

Integrations have zero or more "installations".

An installation provides an integration access to one or more organisational units.

When an organisation wishes to enable your integration we will apply the appropriate changes to their configuration. This creates an installation record.
Each installation may comprise multiple organizations, for example where your integration is enabled for multiple organizations in a group.

The new installation will be accessible at the /app/installations endpoint. You can then use an installation token to access the data you have been granted access to.

Organizational units and parent organizations

It possible for you to create nested organisational units (one organisational unit may contain multiple organisational units - that is, there can be a parent organisation with multiple organisations as children. See the API Reference for more).

The benefits of creating a parent organization is to group together any organizational units that may benefit from extracting blocks of relative and useful information at the same time. For example, searching for transactions and searching purses.

Installation tokens

When you wish to interact with data within Trac you will POST to the /app/installations/${installation-id}/access-tokens endpoint for the installation you wish to use. This returns an access token for the installation that you can use in subsequent calls to the API.

Using your installation token

This is used in the Authorization header with the token keyword:

$ curl -i -H "Authorization: token YOUR_INSTALLATION_ACCESS_TOKEN" -H "Accept: application/json" https://trac.mypebble.co.uk/api/v1/installation/organizations