ChainLaunch

API Authentication

ChainLaunch supports multiple authentication methods for the REST API.

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

The CLI doesn't yet wrap the password-change endpoint. Use the API directly:

curl -X PUT "$CHAINLAUNCH_API_URL/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

chainlaunch api-keys create \
  --name ci-cd-pipeline \
  --role OPERATOR \
  --expires-in 365d

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

chainlaunch api-keys list

Revoke an API Key

chainlaunch api-keys delete <id>

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