Files

GitHub Actions ca477c48d4 chore: Enhance documentation for E2E testing:

- Added clarity and structure to README files, including recent updates and getting started sections.
- Improved manual verification documentation for CrowdSec authentication, emphasizing expected outputs and success criteria.
- Updated debugging guide with detailed output examples and automatic trace capture information.
- Refined best practices for E2E tests, focusing on efficient polling, locator strategies, and state management.
- Documented triage report for DNS Provider feature tests, highlighting issues fixed and test results before and after improvements.
- Revised E2E test writing guide to include when to use specific helper functions and patterns for better test reliability.
- Enhanced troubleshooting documentation with clear resolutions for common issues, including timeout and token configuration problems.
- Updated tests README to provide quick links and best practices for writing robust tests.

2026-03-24 01:47:22 +00:00

4.5 KiB

Raw Blame History

title, description

title	description
REST API	Comprehensive REST API for automation and integrations

REST API

Automate everything. Charon's comprehensive REST API lets you manage hosts, certificates, security rules, and settings programmatically. Perfect for CI/CD pipelines, Infrastructure as Code, or custom integrations.

Overview

The REST API provides full control over Charon's functionality through HTTP endpoints. All responses are JSON-formatted, and the API follows RESTful conventions for resource management.

Base URL: http://your-charon-instance:81/api

Authentication

All API requests require a Bearer token. Generate tokens in Settings → API Tokens.

# Include in all requests
Authorization: Bearer your-api-token-here

Tokens support granular permissions:

Read-only: View configurations without modification
Full access: Complete CRUD operations
Scoped: Limit to specific resource types

Why Use the API?

Use Case	Benefit
CI/CD Pipelines	Automatically create proxy hosts for staging/preview deployments
Infrastructure as Code	Version control your Charon configuration
Custom Dashboards	Build monitoring integrations
Bulk Operations	Manage hundreds of hosts programmatically
GitOps Workflows	Sync configuration from Git repositories

Key Endpoints

Proxy Hosts

# List all proxy hosts
curl -X GET "http://charon:81/api/nginx/proxy-hosts" \
  -H "Authorization: Bearer $TOKEN"

# Create a proxy host
curl -X POST "http://charon:81/api/nginx/proxy-hosts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_names": ["app.example.com"],
    "forward_host": "10.0.0.5",
    "forward_port": 3000,
    "ssl_forced": true,
    "certificate_id": 1
  }'

# Update a proxy host
curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"forward_port": 8080}'

# Delete a proxy host
curl -X DELETE "http://charon:81/api/nginx/proxy-hosts/1" \
  -H "Authorization: Bearer $TOKEN"

SSL Certificates

# List certificates
curl -X GET "http://charon:81/api/nginx/certificates" \
  -H "Authorization: Bearer $TOKEN"

# Request new Let's Encrypt certificate
curl -X POST "http://charon:81/api/nginx/certificates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "letsencrypt",
    "domain_names": ["secure.example.com"],
    "meta": {"dns_challenge": true, "dns_provider": "cloudflare"}
  }'

DNS Providers

# List configured DNS providers
curl -X GET "http://charon:81/api/nginx/dns-providers" \
  -H "Authorization: Bearer $TOKEN"

# Add a DNS provider (for DNS-01 challenges)
curl -X POST "http://charon:81/api/nginx/dns-providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloudflare Production",
    "acme_dns_provider": "cloudflare",
    "meta": {"CF_API_TOKEN": "your-cloudflare-token"}
  }'

Security Settings

# Get WAF status
curl -X GET "http://charon:81/api/security/waf" \
  -H "Authorization: Bearer $TOKEN"

# Enable WAF for a host
curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"waf_enabled": true, "waf_mode": "block"}'

# List CrowdSec decisions
curl -X GET "http://charon:81/api/security/crowdsec/decisions" \
  -H "Authorization: Bearer $TOKEN"

CI/CD Integration Example

GitHub Actions

- name: Create Preview Environment
  run: |
    curl -X POST "${{ secrets.CHARON_URL }}/api/nginx/proxy-hosts" \
      -H "Authorization: Bearer ${{ secrets.CHARON_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{
        "domain_names": ["pr-${{ github.event.number }}.preview.example.com"],
        "forward_host": "${{ steps.deploy.outputs.ip }}",
        "forward_port": 3000
      }'

Error Handling

The API returns standard HTTP status codes:

Code	Meaning
`200`	Success
`201`	Resource created
`400`	Invalid request body
`401`	Invalid or missing token
`403`	Insufficient permissions
`404`	Resource not found
`500`	Server error

Backup & Restore - API-managed backups
SSL Certificates - Certificate automation
Back to Features

4.5 KiB Raw Blame History