API Authentication

ChainLaunch supports multiple authentication methods for the REST API.

Authentication Methods

Method	Edition	Use case	Header
Basic Auth	Community + Pro	Interactive use, scripts	Authorization: Basic base64(user:pass)
API Keys	Pro only	CI/CD, automation, service accounts	X-API-Key: clpro_xxx
OIDC/Bearer Token	Pro only	SSO-integrated apps	Authorization: Bearer <token>

Basic Authentication

The default method. Uses the credentials set at startup.

Default Credentials

# Set during first startup (or via environment variables)
CHAINLAUNCH_USER=admin
CHAINLAUNCH_PASSWORD=admin

Usage

# With curl (username:password)
curl -u admin:admin http://localhost:8100/api/v1/nodes

# Or with explicit header
curl -H "Authorization: Basic $(echo -n 'admin:admin' | base64)" \
  http://localhost:8100/api/v1/nodes

# In scripts
export CHAINLAUNCH_URL="http://localhost:8100"
export CHAINLAUNCH_USER="admin"
export CHAINLAUNCH_PASSWORD="admin"

curl -u "$CHAINLAUNCH_USER:$CHAINLAUNCH_PASSWORD" "$CHAINLAUNCH_URL/api/v1/nodes"

Change Password

curl -X PUT http://localhost:8100/api/v1/auth/password \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{"currentPassword": "admin", "newPassword": "your-new-password"}'

warning

Change the default admin/admin credentials immediately in production.

API Keys (Pro)

API keys are long-lived tokens prefixed with clpro_. Use them for automation, CI/CD pipelines, and service-to-service communication.

Create an API Key

curl -X POST http://localhost:8100/api/v1/auth/api-keys \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-cd-pipeline",
    "role": "OPERATOR",
    "expiresInDays": 365
  }'

Response:

{
  "id": "key-123",
  "name": "ci-cd-pipeline",
  "key": "clpro_abc123def456...",
  "role": "OPERATOR",
  "expiresAt": "2027-03-24T00:00:00Z"
}

warning

The full key is only shown once at creation time. Store it securely.

Use an API Key

curl -H "X-API-Key: clpro_abc123def456..." \
  http://localhost:8100/api/v1/nodes

List API Keys

curl -u admin:admin http://localhost:8100/api/v1/auth/api-keys | jq

Revoke an API Key

curl -X DELETE http://localhost:8100/api/v1/auth/api-keys/key-123 \
  -u admin:admin

API Key Roles

Each API key is assigned a role that determines its permissions:

Role	Permissions	Typical use
ADMIN	Full access	Platform management
OPERATOR	Create/manage nodes, networks, keys	CI/CD, automation
VIEWER	Read-only access	Monitoring, dashboards

See RBAC & Permissions for the full permission matrix.

OIDC/Bearer Tokens (Pro)

When SSO/OIDC is configured, users authenticate through your identity provider and receive a bearer token.

Usage

# After authenticating through your IdP
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:8100/api/v1/nodes

Bearer tokens are typically short-lived (1-24 hours) and refreshed by the frontend automatically. For long-lived access, use API keys instead.

Terraform Authentication

The Terraform provider supports basic auth:

provider "chainlaunch" {
  url      = "http://localhost:8100"
  username = "admin"
  password = var.chainlaunch_password
}

Or use environment variables:

export CHAINLAUNCH_URL="http://localhost:8100"
export CHAINLAUNCH_USERNAME="admin"
export CHAINLAUNCH_PASSWORD="your-password"

terraform plan

Security Best Practices

1. Change default credentials — never run production with admin/admin
2. Use API keys for automation — don't embed user passwords in scripts
3. Set key expiration — rotate API keys at least yearly
4. Use VIEWER role for monitoring — don't give dashboards ADMIN access
5. Enable OIDC in production — centralize authentication through your IdP
6. Use HTTPS — never send credentials over unencrypted HTTP in production
7. Audit key usage — review audit logs for authentication events

Next Steps

• RBAC & Permissions for the full permission matrix
• SSO/OIDC for identity provider integration
• API Reference for all available endpoints
• Security Best Practices for production hardening