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 your Teamleader Focus integrations and sign in with your Teamleader account.
2. Click Create integration, enter a name and proceed to the next page.
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.
5. Fill in the remaining (required) fields.
6. Click the button to save changes, unless making your app public you don't need to request publication.

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 remove the redirect URI from the integration in Teamleader Developers Portal to invalidate the OAuth tokens server-side. Please note that created integration cannot be removed.

---

Related

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