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	Authorization: Bearer clpro_xxx
OIDC/Bearer Token	Pro only	SSO-integrated apps	Authorization: Bearer <token>

Basic Authentication

The default method. Uses the credentials set when ChainLaunch first started — there is no built-in default password.

Where your password came from

Install method	Username	Password
deploy.sh script	admin	Auto-generated, printed on completion and saved to ~/.chainlaunch/credentials.txt
Manual / systemd	Whatever you set as CHAINLAUNCH_USER on first start	Whatever you set as CHAINLAUNCH_PASSWORD on first start

If you forgot the password, restart chainlaunch serve once with CHAINLAUNCH_PASSWORD=<new> exported — the server will reset that user's password and promote them to admin.

The examples below use admin:CHANGE_ME — substitute your real password.

Usage

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

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

# In scripts — source the credentials file written by deploy.sh
source ~/.chainlaunch/credentials.txt

curl -u "$CHAINLAUNCH_USER:$CHAINLAUNCH_PASSWORD" "$CHAINLAUNCH_API_URL/nodes"

Change Password

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

tip

The deploy.sh installer generates a strong random password by default. If you set a weak one manually for first-time access, rotate it with the call above before exposing the API publicly.

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/api-keys \
  -u admin:CHANGE_ME \
  -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 "Authorization: Bearer clpro_abc123def456..." \
  http://localhost:8100/api/v1/nodes

List API Keys

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

Revoke an API Key

curl -X DELETE http://localhost:8100/api/v1/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. Use a strong admin password — deploy.sh generates one for you; if you set it manually via CHAINLAUNCH_PASSWORD, use a long random string
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