Skip to main content

API Client Configuration

The User Tasks Bridge API Client requires minimal configuration. You only need to provide three values when creating a client instance: baseUrl, tenantId, and accessToken.

Configuration Options​

baseUrl​

The URL where your User Tasks Bridge Backend is hosted.

  • Type: string
  • Required: Yes
  • Example: "http://localhost:8089" (local development) or "https://utb.example.com" (production)

The base URL should include the protocol (http:// or https://) but not include any trailing paths like /api or /v1.

// Local development
baseUrl: "http://localhost:8089"

// Production
baseUrl: "https://utb.yourcompany.com"

tenantId​

Your organization's tenant ID in LittleHorse.

  • Type: string
  • Required: Yes
  • Default: "default" (for single-tenant setups)

The tenant ID is used to isolate resources in multi-tenant deployments. For most single-tenant setups, use "default".

// Single-tenant setup (most common)
tenantId: "default"

// Multi-tenant setup
tenantId: "acme-corp"

accessToken​

A valid OAuth access token from your configured Identity Provider.

  • Type: string
  • Required: Yes
  • Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

The access token must be obtained through your IdP's OAuth/OIDC flow. The token is used to authenticate requests to the User Tasks Bridge Backend.

// Token from your IdP authentication flow
accessToken: await getAccessTokenFromIdP()

Basic Configuration​

Here's the minimal configuration needed to create an API Client instance:

import { LHSWBApiClient } from "@littlehorse-enterprises/user-tasks-bridge-api-client";

const client = new LHSWBApiClient({
  baseUrl: "http://localhost:8089",
  tenantId: "default",
  accessToken: "<your-access-token>",
});

That's it! The configuration is essentially a single line of code (plus the import statement).

Getting Configuration Values​

Finding Your baseUrl​

The baseUrl is the URL where your User Tasks Bridge Backend service is running. To find it:

  1. Check your deployment configuration - If you deployed the backend yourself, use the URL where it's accessible
  2. Check your environment variables - If configured via environment variables, look for UTB_BASE_URL or similar
  3. Ask your administrator - If the backend is managed by your organization, contact your admin
  4. Local development - If running locally, it's typically http://localhost:8089 (the default port)

You can verify the backend is accessible by visiting the OpenAPI docs at {baseUrl}/swagger-ui.html.

Finding Your tenantId​

The tenantId is configured in your User Tasks Bridge Backend. To find it:

  1. Check your backend configuration - Look in your oidc-properties.yml file for the tenant-id property
  2. Default value - If not specified, the default is "default"
  3. Ask your administrator - If unsure, contact your backend administrator

Example from backend configuration:

com:
  c4-soft:
    springaddons:
      oidc:
        ops:
          - iss: https://your-idp.com/realms/your-realm
            tenant-id: default  # This is your tenantId

Getting Your accessToken​

The accessToken must be obtained through your Identity Provider's OAuth/OIDC authentication flow. The exact steps depend on your IdP, but typically involve:

  1. Redirecting the user to your IdP for authentication
  2. Exchanging the authorization code for tokens using Authorization Code flow with PKCE
  3. Extracting the access token from the token response

For single-page applications (SPAs), use the Authorization Code flow with PKCE. Most OIDC libraries handle this for you:

// Example with a hypothetical OIDC library
import { OktaAuth } from "@okta/okta-auth-js";

const oktaAuth = new OktaAuth({
  issuer: "https://your-idp.com/oauth2/default",
  clientId: "your-client-id",
  redirectUri: window.location.origin + "/callback",
});

// Get access token
const token = await oktaAuth.getAccessToken();

For more details on authentication, see the Developer Guide and OIDC Primer.

Configuration Patterns​

Using Environment Variables​

For different environments (development, staging, production), use environment variables:

const client = new LHSWBApiClient({
  baseUrl: process.env.REACT_APP_UTB_BASE_URL || "http://localhost:8089",
  tenantId: process.env.REACT_APP_TENANT_ID || "default",
  accessToken: await getAccessToken(), // Get from your IdP
});

Creating a Client Factory​

Create a reusable function to create clients with consistent configuration:

import { LHSWBApiClient } from "@littlehorse-enterprises/user-tasks-bridge-api-client";

async function createApiClient() {
  const accessToken = await getAccessToken(); // Your token retrieval logic
  
  return new LHSWBApiClient({
    baseUrl: process.env.REACT_APP_UTB_BASE_URL || "http://localhost:8089",
    tenantId: process.env.REACT_APP_TENANT_ID || "default",
    accessToken: accessToken,
  });
}

// Use it
const client = await createApiClient();
const tasks = await client.listUserTasks({ limit: 10 });

React Hook Example​

Create a React hook for managing the API client:

import { useState, useEffect } from "react";
import { LHSWBApiClient } from "@littlehorse-enterprises/user-tasks-bridge-api-client";

function useApiClient() {
  const [client, setClient] = useState<LHSWBApiClient | null>(null);

  useEffect(() => {
    async function initClient() {
      const accessToken = await getAccessToken(); // Your token logic
      
      const apiClient = new LHSWBApiClient({
        baseUrl: process.env.REACT_APP_UTB_BASE_URL || "http://localhost:8089",
        tenantId: process.env.REACT_APP_TENANT_ID || "default",
        accessToken: accessToken,
      });
      
      setClient(apiClient);
    }
    
    initClient();
  }, []);

  return client;
}

Token Refresh​

Access tokens expire after a period of time (typically 5-15 minutes). When the token expires, you'll receive an UnauthorizedError from API calls. You'll need to:

  1. Refresh the token using your IdP's refresh token
  2. Create a new client instance with the new access token
  3. Retry the API call

Most OIDC libraries handle token refresh automatically. If your library supports token refresh callbacks, you can update the client when tokens are refreshed:

import { LHSWBApiClient, UnauthorizedError } from "@littlehorse-enterprises/user-tasks-bridge-api-client";

// Example pattern for token refresh
let accessToken = await getAccessToken();

const client = new LHSWBApiClient({
  baseUrl: "http://localhost:8089",
  tenantId: "default",
  accessToken: accessToken,
});

// When token expires, refresh and create new client
try {
  await client.listUserTasks({ limit: 10 });
} catch (error) {
  if (error instanceof UnauthorizedError) {
    // Refresh token
    accessToken = await refreshAccessToken();
    // Create new client with refreshed token
    const refreshedClient = new LHSWBApiClient({
      baseUrl: "http://localhost:8089",
      tenantId: "default",
      accessToken: accessToken,
    });
    // Retry with new client
    await refreshedClient.listUserTasks({ limit: 10 });
  }
}

For more details on error handling, see the Error Handling Guide.

Configuration Validation​

The API Client validates the configuration when you create an instance. If any required field is missing or invalid, you'll get an error immediately. Common issues:

  • Missing baseUrl - Will throw an error
  • Invalid baseUrl format - Must include protocol (http:// or https://)
  • Missing tenantId - Will throw an error
  • Missing accessToken - Will throw an error (though API calls will fail with UnauthorizedError)

Next Steps​