Skip to content
DADL

Add Authentication

DADL supports several authentication methods. This guide shows how to configure each one and how credentials flow through ToolMesh.

How credentials work

Section titled “How credentials work”

Credentials are never stored in DADL files. The flow is:

  1. You define auth.credential: my_token in the DADL file
  2. You set the environment variable CREDENTIAL_MY_TOKEN=secret123 in ToolMesh’s environment
  3. At request time, ToolMesh reads the credential and injects it into the HTTP request
  4. The AI agent never sees the actual secret

Bearer token

Section titled “Bearer token”

The most common pattern for APIs that use Authorization: Bearer <token>:

auth:
  type: bearer
  credential: github_token
  inject_into: header
  header_name: Authorization
  prefix: "Bearer "

Set the credential:

Terminal window
export CREDENTIAL_GITHUB_TOKEN=ghp_xxxxxxxxxxxx

API key in header

Section titled “API key in header”

For APIs that expect a custom header like X-API-Key:

auth:
  type: apikey
  credential: acme_api_key
  inject_into: header
  header_name: X-API-Key

No prefix needed — the raw credential value is sent as the header value.

API key in query string

Section titled “API key in query string”

Some APIs pass the key as a URL parameter:

auth:
  type: apikey
  credential: shelly_auth_key
  inject_into: query
  query_param: auth_key

This appends ?auth_key=<value> to every request.

Basic authentication

Section titled “Basic authentication”

For username/password APIs:

auth:
  type: basic
  credential: my_service_creds

The credential value should be username:password — ToolMesh handles Base64 encoding.

Setup block

Section titled “Setup block”

Always include a setup block so users know how to obtain and configure credentials:

setup:
  credential_steps:
    - "Navigate to Settings → API Keys"
    - "Click 'Generate new key'"
    - "Copy the key value"
  env_var: CREDENTIAL_ACME_API_KEY
  required_scopes:
    - read
    - write
  optional_scopes:
    - admin
  docs_url: "https://docs.example.com/auth"
  notes: >
    Keys expire after 90 days. Rotate them in the
    ToolMesh credential store before expiry.

The env_var field tells the user exactly which environment variable to set. Convention: CREDENTIAL_ + uppercase credential name.

Multiple credentials

Section titled “Multiple credentials”

If an API needs multiple credentials (e.g. an auth key plus a separate server identifier), use the credential store and reference them in composites or setup notes.

Next steps

Section titled “Next steps”