Overview

This document provides an overview of the Trac sandbox environment, detailing its purpose, setup process, and key considerations for integrators. The sandbox serves as a first testing environment for integration partners, allowing them to develop and validate their Trac integration before scheduling a test session with the Pebble team, then moving onto production.

Purpose

The sandbox environment is designed to:

Allow integration partners to validate authentication and various processes.
Provide integrators with a controlled space to test API calls and data flows.
Facilitate debugging and troubleshooting.

Scope

This guide covers:

Steps to access and configure the sandbox.
Authentication requirements.
Common issues and troubleshooting tips.

Description

Available Environments

Trac provides three environments:

Demo (Sandbox) – A testing environment where integrators can freely experiment with API calls and workflows.
Integration – Used for testing Trac’s own integrations and for partners to verify their implementations during scheduled test sessions. Integrators can find more information on the testing process here.
Production – The live environment where fully tested integrations operate.

Accessing the Sandbox

To gain access to the sandbox, integrators must:

Generate a public and private key.
Send the public key to [email protected] for setup. Integrators will receive sandbox credentials and access details to the sandbox.
They may also request:
- Pre-created members for testing.
- Dummy transactions to simulate real-world operations.

Authentication & Key Setup

Authentication involves two key steps:

JWT Token Generation – Uses the public/private key pair to generate a JWT token.
Installation Access Token – Obtained using the JWT token, this grants access to API operations like transaction creation and member management.

Risks & Mitigations

The most frequent issues integrators encounter usually revolve around incorrect JWT token generation – Due to missing required parameters or incorrect formatting. You can find a recipe page here, and read this page for more information on JWTs.

Glossary & Additional Resources

JWT (JSON Web Token) – A token used for authentication, generated using a private key and verified with a public key.
Installation Access Token – A token that grants access to API operations after JWT authentication.
Public/Private Key Pair – A cryptographic key pair used for secure authentication. The private key is kept secret, while the public key is shared with Trac.
Members – User entities within the Trac system that can be assigned transactions. Typically will be the pupils/staff of a school but can also represent other entities (e.g. organisations).
Dummy Transactions – Simulated transactions used for testing within the sandbox.