Automate your infrastructure with the LightYear Cloud REST API, webhooks, Terraform provider, and CLI.
API Keys & Authentication
How do I get an API key?
Go to Dashboard → Access Control → API Keys and click 'Generate API Key'. Give it a descriptive name (e.g. 'Terraform production') and select the permissions you need. Copy the key immediately — it will only be shown once.
How do I authenticate API requests?
Include your API key in the Authorization header of every request: Authorization: Bearer YOUR_API_KEY. All API endpoints require HTTPS. Requests over plain HTTP will be rejected.
Can I create multiple API keys?
Yes. You can create as many API keys as you need — we recommend one key per application or integration. Each key can be given a descriptive label and revoked independently without affecting other integrations.
What should I do if my API key is compromised?
Immediately go to Dashboard → Access Control → API Keys and click 'Revoke' next to the compromised key. Generate a new key and update your integrations. Revoked keys stop working instantly.
REST API
What is the base URL for the API?
The LightYear Cloud API base URL is: https://api.lightyear.host/v1. All endpoints are versioned. We maintain backwards compatibility within a major version and provide at least 6 months notice before deprecating any endpoint.
What format does the API use?
The API accepts and returns JSON. Set Content-Type: application/json on all POST and PATCH requests. Dates are returned in ISO 8601 format (UTC). Pagination uses cursor-based navigation with a next_cursor field.
Are there rate limits?
Yes. The default rate limit is 600 requests per minute per API key. If you exceed this, you will receive a 429 Too Many Requests response with a Retry-After header. Enterprise plans have higher rate limits — contact [email protected].
How do I list all my servers via the API?
Send a GET request to https://api.lightyear.host/v1/instances with your API key in the Authorization header. The response includes an array of instance objects with their ID, label, status, IP address, region, and plan details.
Webhooks
What are webhooks and how do I set them up?
Webhooks allow LightYear Cloud to push real-time event notifications to your application. Go to Dashboard → Access Control → Webhooks, click 'Add Webhook', enter your endpoint URL, and select the events you want to receive.
What events can I subscribe to?
Available webhook events include: instance.created, instance.destroyed, instance.power_on, instance.power_off, instance.snapshot_completed, billing.invoice_created, billing.payment_failed, and more. A full list is available in the API documentation.
How do I verify webhook signatures?
Each webhook request includes an X-LightYear-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret. Always verify this signature before processing the event to prevent spoofing.
Terraform & Infrastructure as Code
Is there a Terraform provider for LightYear Cloud?
Yes. The LightYear Cloud Terraform provider is available on the Terraform Registry. It supports managing instances, SSH keys, firewalls, block storage, and DNS records. Add it to your Terraform configuration with: provider 'lightyear' { api_key = var.lightyear_api_key }.
Can I use Pulumi or Ansible?
Yes. LightYear Cloud's REST API is compatible with any infrastructure-as-code tool that supports HTTP APIs. Community-maintained Pulumi and Ansible modules are available on GitHub. Contact [email protected] for links to the latest community resources.
Is there a CLI tool?
Yes. The LightYear CLI (lyctl) is available for macOS, Linux, and Windows. Install it with: curl -fsSL https://cli.lightyear.host/install.sh | sh. Run lyctl help to see all available commands including server deploy, list, destroy, ssh, and snapshot.
API Security Best Practices
How should I store my API key securely?
Never hardcode API keys in source code or commit them to version control. Use environment variables or a secrets manager (e.g. HashiCorp Vault, AWS Secrets Manager, GitHub Actions Secrets). Rotate keys periodically and immediately if you suspect exposure.
Should I use different API keys for different environments?
Yes. Use separate API keys for development, staging, and production environments. This limits the blast radius if a key is compromised and makes it easy to revoke access for a specific environment without affecting others.
Can I restrict an API key to specific IP addresses?
IP allowlisting for API keys is available on Enterprise plans. Contact [email protected] to enable this feature. For standard plans, we recommend using firewall rules at the application level to restrict which IPs can make API calls.
Need help with an integration?
Our engineering team can help with custom integrations.
Your cookie choices for this website
This site uses cookies and related technologies, as described in our privacy policy, for purposes that may include site operation, analytics, and enhanced user experience. You may choose to consent to our use of these technologies, or manage your own preferences. Cookie policy