Requests & Authentication

Test steps can execute HTTP requests to set up test data, verify backend state, or trigger external actions. This page covers how to configure reusable requests and authentication providers.

File Organization


configs/
├── auth/           # Authentication configurations
│   ├── dev1.json
│   └── prod.json
└── requests/       # Reusable request definitions
    ├── accounts.json
    └── transfers.json

Authentication Configuration

Authentication configs define how to build authorization headers from environment variables.

Static Header Authentication

Use when you have API keys or pre-generated tokens:


{
  "$schema": "https://github.com/lamdis-ai/lamdis-runs/schema/auth-file.v1.json",
  "id": "auth/static-dev",
  "headers": {
    "authorization": "Bearer ${API_TOKEN}",
    "x-api-key": "${BOT_API_KEY}"
  }
}

Set the environment variables:


export API_TOKEN="your-token-here"
export BOT_API_KEY="your-api-key"

OAuth Client Credentials

For OAuth 2.0 client credentials flow:


{
  "$schema": "https://github.com/lamdis-ai/lamdis-runs/schema/auth-file.v1.json",
  "id": "auth/dev1",
  "kind": "oauth_client_credentials",
  "clientId": "${ACCOUNTS_CLIENT_ID}",
  "clientSecret": "${ACCOUNTS_CLIENT_SECRET}",
  "tokenUrl": "https://login.example.com/oauth2/token",
  "scopes": ["accounts.read", "accounts.write"],
  "cacheTtlSeconds": 300,
  "apply": {
    "type": "bearer",
    "header": "authorization"
  }
}

The runner will:

Call tokenUrl using client credentials and scopes
Extract access_token from the response
Cache the token for cacheTtlSeconds
Inject Authorization: Bearer <access_token> header

Properties

Property	Type	Description
`id`	string	Unique identifier (e.g., `auth/dev1`)
`kind`	`"oauth_client_credentials"`	OAuth flow type
`clientId`	string	OAuth client ID (supports `${ENV_VAR}`)
`clientSecret`	string	OAuth client secret (supports `${ENV_VAR}`)
`tokenUrl`	string	Token endpoint URL
`scopes`	string[]	OAuth scopes to request
`cacheTtlSeconds`	number	How long to cache tokens
`apply.type`	`"bearer"`	Token type
`apply.header`	string	Header name (default: `authorization`)

Request Configuration

Request files define reusable HTTP operations that can be called from test steps.

Basic Request


{
  "$schema": "https://github.com/lamdis-ai/lamdis-runs/schema/request-file.v1.json",
  "authRef": "auth/dev1",
  "requests": [
    {
      "id": "accounts.get",
      "transport": {
        "mode": "direct",
        "http": {
          "method": "GET",
          "base_url": "https://api.example.com",
          "path": "/accounts/{accountId}",
          "headers": {
            "content-type": "application/json"
          }
        }
      }
    }
  ]
}

Request with Body Template


{
  "authRef": "auth/dev1",
  "requests": [
    {
      "id": "accounts.create_test",
      "transport": {
        "mode": "direct",
        "http": {
          "method": "POST",
          "base_url": "https://api.example.com",
          "path": "/accounts",
          "headers": {
            "content-type": "application/json"
          },
          "body": {
            "account_id": "{accountId}",
            "status": "{status}",
            "balance": "{balance}",
            "owner": "{owner}"
          }
        }
      }
    }
  ]
}

The {key} placeholders in the body are replaced with values from the step’s inputMappings.

Request Properties

Property	Type	Description
`id`	string	Unique request identifier (e.g., `accounts.create_test`)
`transport.mode`	`"direct"`	Transport mode
`transport.http.method`	string	HTTP method (`GET`, `POST`, `PUT`, `DELETE`)
`transport.http.base_url`	string	Base URL for the request
`transport.http.path`	string	URL path (can include `{param}` placeholders)
`transport.http.headers`	object	Additional headers
`transport.http.body`	object	Request body template

Using Requests in Steps

Reference requests from your test steps:


{
  "type": "request",
  "id": "setup_account",
  "requestId": "accounts.create_test",
  "inputMappings": {
    "accountId": "acct-test-001",
    "status": "active",
    "balance": 5000,
    "owner": "Test User"
  },
  "saveAs": "createdAccount"
}

Input Mappings

The inputMappings object provides values for:

Body placeholders — {key} in the request body
Path parameters — {param} in the URL path
Dynamic values — Can use variable interpolation


{
  "type": "request",
  "requestId": "accounts.get",
  "inputMappings": {
    "accountId": "${bag.var.createdAccount.id}"
  }
}

Saving Results

Use saveAs to store the response in the variable bag:


{
  "type": "request",
  "requestId": "accounts.get",
  "saveAs": "accountDetails"
}

Access later via ${bag.var.accountDetails.balance}.

Or use id for step-based access:


{
  "type": "request",
  "id": "get_acct",
  "requestId": "accounts.get"
}

Access via $steps.get_acct.output.balance.

Assistant Configuration

Assistants define how to communicate with your AI endpoint.

HTTP Chat Assistant


{
  "$schema": "https://github.com/lamdis-ai/lamdis-runs/schema/assistant-file.v1.json",
  "id": "assistants/dev/v1",
  "name": "Dev Assistant v1",
  "authRef": "auth/dev1",
  "env": {
    "channel": "http_chat",
    "baseUrl": "https://assistant-dev.example.com",
    "timeoutMs": 20000,
    "headers": {
      "x-api-key": "${BOT_API_KEY}"
    }
  },
  "path": "/chat",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string" },
      "transcript": { "type": "array" }
    },
    "required": ["message"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "reply": { "type": "string" }
    },
    "required": ["reply"]
  }
}

Assistant Properties

Property	Type	Description
`id`	string	Unique identifier (e.g., `assistants/dev/v1`)
`name`	string	Human-readable name
`authRef`	string	Reference to auth config
`env.channel`	string	Execution channel (`http_chat`, `openai_chat`, `bedrock_chat`)
`env.baseUrl`	string	Base URL for HTTP channel
`env.timeoutMs`	number	Request timeout in milliseconds
`env.headers`	object	Additional headers (supports `${ENV_VAR}`)
`path`	string	Chat endpoint path (default: `/chat`)
`inputSchema`	object	Expected input JSON schema
`outputSchema`	object	Expected output JSON schema

Personas

Personas define simulated end-users for your tests:


{
  "personas": [
    {
      "id": "retail-us-anxious",
      "description": "US retail customer with low financial literacy, anxious about markets.",
      "userProfile": {
        "ageRange": "25-34",
        "jurisdiction": "US",
        "segment": "retail",
        "riskTolerance": "low"
      }
    },
    {
      "id": "business-owner",
      "description": "Small business owner looking for accounting help.",
      "userProfile": {
        "segment": "business",
        "companySize": "1-10"
      }
    }
  ]
}

Reference personas in message steps:


{
  "script": {
    "messages": [
      {
        "role": "user",
        "personaId": "retail-us-anxious",
        "content": "I want to move all my savings into cryptocurrency"
      }
    ]
  }
}

Suites

Suites group tests and assistants together:


{
  "$schema": "https://github.com/lamdis-ai/lamdis-runs/schema/suite-file.v1.json",
  "id": "legal-tests",
  "description": "Legal and compliance-oriented tests",
  "assistants": {
    "includeFolders": ["assistants/dev"],
    "include": ["assistants/dev/v1"],
    "exclude": []
  },
  "tests": {
    "includeFiles": ["tests/finra-checks/p1-tests.json"],
    "includeIds": ["finra-suitability-p1"]
  }
}

Suite Properties

Property	Type	Description
`id`	string	Suite identifier
`description`	string	Human-readable description
`assistants.include`	string[]	Specific assistant IDs to include
`assistants.includeFolders`	string[]	Include all assistants in folders
`assistants.exclude`	string[]	Assistant IDs to exclude
`tests.includeFiles`	string[]	Test file paths to include
`tests.includeIds`	string[]	Specific test IDs to include

Complete Example

Auth (`auth/dev1.json`)


{
  "id": "auth/dev1",
  "kind": "oauth_client_credentials",
  "clientId": "${DEV_CLIENT_ID}",
  "clientSecret": "${DEV_CLIENT_SECRET}",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "scopes": ["api:read", "api:write"],
  "cacheTtlSeconds": 600,
  "apply": { "type": "bearer", "header": "authorization" }
}

Request (`requests/accounts.json`)


{
  "authRef": "auth/dev1",
  "requests": [
    {
      "id": "accounts.create_test",
      "transport": {
        "mode": "direct",
        "http": {
          "method": "POST",
          "base_url": "https://api.example.com",
          "path": "/accounts",
          "body": { "balance": "{balance}", "name": "{name}" }
        }
      }
    },
    {
      "id": "accounts.get",
      "transport": {
        "mode": "direct",
        "http": {
          "method": "GET",
          "base_url": "https://api.example.com",
          "path": "/accounts/{accountId}"
        }
      }
    }
  ]
}

Test (`tests/account-tests.json`)


{
  "imports": {
    "requests": ["requests/accounts.json"]
  },
  "assistantRef": "assistants/dev/v1",
  "tests": [
    {
      "id": "account-balance-check",
      "name": "Verify account balance query",
      "steps": [
        {
          "type": "request",
          "id": "create",
          "requestId": "accounts.create_test",
          "inputMappings": { "balance": 1000, "name": "Test Account" },
          "saveAs": "account"
        },
        {
          "type": "message",
          "content": "What's the balance of account ${bag.var.account.id}?"
        },
        {
          "type": "assistant_check",
          "mode": "judge",
          "rubric": "The assistant should report a balance of $1000"
        }
      ]
    }
  ]
}

Next Steps

Variable Interpolation — Dynamic value syntax
Test Steps — Step type reference
CI/CD Integration — Automate test runs