Installation & Configuration

Installation & Configuration

Everything you need to go from zero to a working Teamleader connection.

---

Prerequisites

Requirement	Version
PHP	8.2 or higher
Laravel	10.x, 11.x, or 12.x
Database	MySQL 5.7+ / PostgreSQL 10+ / SQLite 3.8+
Cache driver	Any Laravel cache driver (Redis strongly recommended for production)

You also need a Teamleader Marketplace application — see Create a Marketplace App below.

---

Install the Package

composer require mcore-services-bv/teamleader-sdk

Publish the configuration file:

php artisan vendor:publish --tag=teamleader-config

This creates config/teamleader.php in your application. The SDK does not require php artisan migrate — the teamleader_tokens table is created automatically on the first successful OAuth callback.

---

Create a Marketplace App

The SDK uses OAuth 2.0. You need a Teamleader Marketplace application to get your client_id and client_secret.

1. Go to marketplace.teamleader.eu and sign in with your Teamleader account.
2. Click Add integration → choose Private (for internal use) or Public.
3. Set the Redirect URI to https://your-app.com/teamleader/callback — this must match TEAMLEADER_REDIRECT_URI in your .env exactly.
4. Copy the Client ID and Client Secret from the app detail page.

For local development, APP_URL is typically http://localhost or http://127.0.0.1:8000. Teamleader accepts http:// redirect URIs for local development only.

---

Required .env Variables

TEAMLEADER_CLIENT_ID=your_client_id
TEAMLEADER_CLIENT_SECRET=your_client_secret
TEAMLEADER_REDIRECT_URI=${APP_URL}/teamleader/callback

The SDK will throw a ConfigurationException on boot if any of these three are missing.

---

Full .env Reference

All variables and their defaults:

# ── Required ──────────────────────────────────────────────────
TEAMLEADER_CLIENT_ID=
TEAMLEADER_CLIENT_SECRET=
TEAMLEADER_REDIRECT_URI=${APP_URL}/teamleader/callback

# ── API ───────────────────────────────────────────────────────
TEAMLEADER_API_VERSION=2023-09-26   # API version header sent with every request

# ── HTTP timeouts (seconds) ───────────────────────────────────
TEAMLEADER_API_TIMEOUT=30
TEAMLEADER_API_CONNECT_TIMEOUT=10
TEAMLEADER_API_READ_TIMEOUT=25

# ── Retries ───────────────────────────────────────────────────
TEAMLEADER_API_RETRY_ATTEMPTS=3
TEAMLEADER_API_RETRY_DELAY=1000     # milliseconds between attempts

# ── Rate limiting ─────────────────────────────────────────────
TEAMLEADER_RATE_LIMITING_ENABLED=true
TEAMLEADER_RATE_LIMIT=200           # Teamleader's limit: 200 req/min
TEAMLEADER_THROTTLE_THRESHOLD=0.7   # Start throttling at 70% usage
TEAMLEADER_AGGRESSIVE_THROTTLING=true
TEAMLEADER_RESPECT_RETRY_AFTER=true

# ── Logging ───────────────────────────────────────────────────
TEAMLEADER_LOG_REQUESTS=false       # Log every outgoing request (verbose)
TEAMLEADER_LOG_RESPONSES=false      # Log every API response (verbose)
TEAMLEADER_LOG_RATE_LIMITS=true
TEAMLEADER_LOG_TOKEN_REFRESH=true
TEAMLEADER_LOG_CHANNEL=            # Defaults to your app's default log channel
TEAMLEADER_SANITIZE_LOGS=true      # Redact tokens from log output

---

Set Up OAuth Routes

Add two routes to your application. The exact paths can be anything — just make sure TEAMLEADER_REDIRECT_URI matches your callback route.

// routes/web.php
use McoreServices\TeamleaderSDK\Facades\Teamleader;

// Step 1: redirect the user to Teamleader to authorise
Route::get('/teamleader/connect', function () {
    return Teamleader::authorize();
})->middleware('auth');

// Step 2: Teamleader redirects back here with a code
Route::get('/teamleader/callback', function (Request $request) {
    if (Teamleader::handleCallback($request->get('code'), $request->get('state'))) {
        return redirect('/dashboard')->with('success', 'Connected to Teamleader!');
    }
    return redirect('/settings')->with('error', 'Connection failed. Please try again.');
});

Exempt the Callback from CSRF

Laravel's CSRF middleware will block the OAuth callback unless you exclude it:

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'teamleader/callback',
    ]);
})

// app/Http/Middleware/VerifyCsrfToken.php (Laravel 10)
protected $except = [
    'teamleader/callback',
];

---

Verify the Connection

Once you've completed the OAuth flow, run these commands to confirm everything is working:

# Connection and token status
php artisan teamleader:status

# Full configuration validation
php artisan teamleader:config:validate

# Live API health check
php artisan teamleader:health

Or test directly in Tinker:

php artisan tinker
>>> Teamleader::isAuthenticated()  # should return true
>>> Teamleader::companies()->list()

---

Production Checklist

Before going live, verify these additional settings:

• CACHE_DRIVER=redis — file cache does not coordinate across queue workers
• Redis is password-protected with TLS enabled (REDIS_SCHEME=tls)
• .env is excluded from version control (.gitignore)
• APP_KEY is unique and not shared between environments
• TEAMLEADER_SANITIZE_LOGS=true to keep tokens out of log files
• TEAMLEADER_LOG_REQUESTS and TEAMLEADER_LOG_RESPONSES are false in production

For token encryption and additional hardening, see Token-Storage-&-Security.

---

Disconnecting

To revoke the connection and clear all stored tokens:

Teamleader::logout();

Or from the command line:

php artisan teamleader:token --revoke

After revoking, also disconnect the integration in Teamleader Marketplace to invalidate the OAuth tokens server-side.

---

Related

• Usage — Common operations, filtering, pagination, error handling
• Token-Storage-&-Security — How tokens are stored and how to harden for production
• Errors — Exception reference