Authentication

The Farseer Client supports three authentication methods.

Method 1: Environment Variables (Recommended for Farseer Apps)

When running inside a Farseer environment (remote jobs, Farseer Apps), the client auto-configures from environment variables:

const client = new FarseerClient();

Required environment variables:

Variable	Description	Example
TENANT_ID	Your Farseer tenant identifier	my-company
FARSEER_API_KEY	API authentication key	fsk_a1b2c3d4...
FARSEER_URL	Base URL for Farseer server	https://my-company.farseer.io

Method 2: Constructor Parameters

Pass credentials directly:

const client = new FarseerClient(
    'my-tenant-id',     // tenantId
    'my-api-key',       // apiKey
    'https://my-company.farseer.io'  // basePath
);

Method 3: Custom Configuration

For advanced use cases (custom headers, middleware, etc.):

const client = new FarseerClient({
    basePath: 'https://my-company.farseer.io/api/v3',
    headers: {
        'X-TENANT-ID': 'my-tenant-id',
        'X-API-KEY': 'my-api-key',
        'Custom-Header': 'value',
    },
});

Configuration Options

interface ConfigurationParameters {
    basePath?: string;              // Server URL
    headers?: Record<string, string>; // Custom headers
    apiKey?: string | ((name: string) => string);
    accessToken?: string | Promise<string>;
    middleware?: Middleware[];       // Request/response middleware
    fetchApi?: FetchAPI;           // Custom fetch implementation
    credentials?: RequestCredentials;
}

Development vs Production Pattern

A common pattern for switching between development and production:

import * as farseer from 'farseer-client';

const isDevelopment =
    process.env.FARSEER_URL === undefined &&
    process.env.FARSEER_API_KEY === undefined;

const DEV_TENANT_ID = 'your-tenant-dev';
const DEV_API_KEY = 'your_dev_api_key_here';
const DEV_URL = 'https://your-tenant-dev.farseer.io/api/v3';

let client: farseer.FarseerClient;

if (isDevelopment) {
    console.log('Running in DEVELOPMENT mode');
    client = new farseer.FarseerClient(DEV_TENANT_ID, DEV_API_KEY, DEV_URL);
} else {
    console.log('Running in PRODUCTION mode');
    client = new farseer.FarseerClient();
}

caution

Always test against a development Farseer instance before deploying to production. This prevents accidental data modifications in production environments.

API Key Management

API keys are created through the Farseer API:

const apiKey = await client.apiKeys.create({
    serviceUserId: serviceUser.id
});

// The key value is only shown once!
console.log('API Key:', apiKey.value);

Headers Sent Automatically

The client automatically includes these headers:

Header	Value	Description
X-TENANT-ID	Your tenant ID	Identifies the tenant
X-API-KEY	Your API key	Authentication
X-API-VERSION	SDK version	API compatibility