or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

async-operations.md authentication.md cache.md errors.md index.md logging.md transport.md user-agent.md

tile.json

Authentication

Authentication functionality for Algolia API access with configurable credential placement and header/query parameter management.

Capabilities

Create Authentication

Creates an authentication object that manages API credentials and provides methods for accessing them in different formats.

/**
 * Creates an authentication object for Algolia API access
 * @param appId - The Algolia application ID
 * @param apiKey - The Algolia API key
 * @param authMode - Where to place credentials ('WithinHeaders' or 'WithinQueryParameters')
 * @returns Authentication object with methods to retrieve headers and query parameters
 */
function createAuth(
  appId: string,
  apiKey: string,
  authMode?: AuthMode
): {
  readonly headers: () => Headers;
  readonly queryParameters: () => QueryParameters;
};

Usage Examples:

import { createAuth } from "@algolia/client-common";

// Default authentication (credentials in headers)
const auth = createAuth("YourApplicationID", "YourAPIKey");

// Get headers for requests
const headers = auth.headers();
// Returns: { 'x-algolia-api-key': 'YourAPIKey', 'x-algolia-application-id': 'YourApplicationID' }

const queryParams = auth.queryParameters();
// Returns: {} (empty when using headers)

// Authentication with credentials in query parameters
const authQuery = createAuth(
  "YourApplicationID", 
  "YourAPIKey", 
  "WithinQueryParameters"
);

const headersQuery = authQuery.headers();
// Returns: {} (empty when using query parameters)

const queryParamsQuery = authQuery.queryParameters();
// Returns: { 'x-algolia-api-key': 'YourAPIKey', 'x-algolia-application-id': 'YourApplicationID' }

Authentication Modes

The authentication system supports two modes for credential placement:

/**
 * Authentication mode defining where credentials are placed
 */
type AuthMode = 'WithinHeaders' | 'WithinQueryParameters';

WithinHeaders (default): Places credentials in HTTP headers
WithinQueryParameters: Places credentials in URL query parameters

Headers Method

Returns HTTP headers containing authentication credentials when using header-based authentication.

/**
 * Returns authentication headers
 * @returns Headers object containing credentials or empty object if using query parameters
 */
headers(): Headers;

Query Parameters Method

Returns query parameters containing authentication credentials when using query parameter-based authentication.

/**
 * Returns authentication query parameters
 * @returns Query parameters object containing credentials or empty object if using headers
 */
queryParameters(): QueryParameters;

Integration Examples

With Transport Layer:

import { createAuth, createTransporter } from "@algolia/client-common";

const auth = createAuth("YourApplicationID", "YourAPIKey");

const transporter = createTransporter({
  // ... other options
  baseHeaders: auth.headers(),
  baseQueryParameters: auth.queryParameters(),
});

Manual Request Construction:

import { createAuth } from "@algolia/client-common";

const auth = createAuth("YourApplicationID", "YourAPIKey");

// Build request with authentication
const request = {
  method: 'GET' as const,
  path: '/1/indexes',
  headers: {
    'Content-Type': 'application/json',
    ...auth.headers()
  },
  queryParameters: {
    ...auth.queryParameters(),
    // ... other query parameters
  }
};

Security Considerations

API keys are sensitive credentials that should be protected
The authentication object stores credentials in memory
Consider using environment variables for API key storage
When using query parameter mode, be aware that credentials may appear in server logs