Skip to main content

Authentication Flows

This guide demonstrates how to test APIs with different authentication methods using Dochia.

Overview​

Dochia supports multiple authentication mechanisms via CLI flags and headers:

  • Basic authentication: --user <user:password>
  • Static headers: --header name=value
  • Headers file: --headers headers.yml (root key: all)
  • Token refresh for long runs: --auth-refresh <sec>, --auth-refresh-script <script>
  • Proxy and client certs: --proxy, --ssl-keystore, --ssl-keystore-password, --ssl-key-password

Prerequisites​

  • OpenAPI spec: -c, --contract
  • Service URL: -s, --server

Basic Authentication​

# Using --user flag
dochia test -c openapi.yml -s https://api.example.com --user "username:password"

API Key Authentication​

# In header
dochia test -c openapi.yml -s https://api.example.com \
  --header "X-API-Key=your-api-key-here"

# In query parameter
dochia test -c openapi.yml -s "https://api.example.com?api_key=key-here"

Bearer Token​

# Static token
dochia test -c openapi.yml -s https://api.example.com \
  --header "Authorization=Bearer your-token-here"

# From environment
export TOKEN=your-token-here
dochia test -c openapi.yml -s https://api.example.com \
  --header "Authorization=Bearer $TOKEN"

OAuth 2.0​

# Get token
token=$(curl -X POST https://auth.example.com/oauth/token \
  -d "client_id=id" -d "client_secret=secret" \
  -d "grant_type=client_credentials" | jq -r '.access_token')

# Use token
dochia test -c openapi.yml -s https://api.example.com \
  --header "Authorization=Bearer $token"

JWT Authentication​

# With static JWT
dochia test -c openapi.yml -s https://api.example.com \
  --header "Authorization=Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Custom Headers​

# headers.yml
all:
  X-Custom-Auth: "your-auth-value"
  X-Request-ID: "$(uuidgen)"

# Usage:
# dochia test -c openapi.yml -s https://api.example.com --headers headers.yml

Authentication Script​

# auth-script.sh

#!/bin/bash
echo "Bearer $(get_token_from_vault)"
# Make executable: 

chmod +x auth-script.sh

# Usage:
dochia test -c openapi.yml -s https://api.example.com \
  --headers headers.yml \
  --auth-refresh-script ./auth-script.sh \
  --auth-refresh 300

Headers file pattern for refresh​

# headers.yml
all:
  Authorization: auth_script

Proxy and Client Certificates​

# Proxy (full URI)
dochia test -c openapi.yml -s https://api.example.com \
  --proxy http://proxy.company.com:8080

# Client certificates (mTLS)
dochia test -c openapi.yml -s https://api.example.com \
  --ssl-keystore client.p12 \
  --ssl-keystore-password "$KEYSTORE_PASS" \
  --ssl-key-password "$KEY_PASS"

Troubleshooting​

  • 401/403 Errors: Verify header names/values, scopes, and target environment
  • Token Expiration: Use --auth-refresh with --auth-refresh-script
  • Headers Not Applied: Ensure YAML root is all; use Authorization: auth_script when refreshing
  • Connection Issues: Configure --proxy and SSL settings as needed
  • Debugging: Use --dry-run and -vvv to inspect effective headers

Security Tips​

  • Mask sensitive headers in console output and reports: 
    --mask-headers "Authorization,X-API-Key"
  • Prefer environment variables for secrets. Avoid committing tokens in files.
  • Limit scope when possible (paths, tags, methods) while validating auth.

See Also​