API Keys

API keys are your credentials for programmatic access to WAYSCloud services. Every API call requires a valid key.

Key types

WAYSCloud uses three credential types, each for a different purpose:

Service API Key

Scoped to a single service. Created when you activate a service in the dashboard.

• Format: wayscloud_{service}_{10-char prefix}_{56-char secret}
• Example: wayscloud_dns_abc1234567_aBcDeFgHiJkLmNoPqRsTuVwXyZ...
• Use for: DNS, Storage, LLM, Verify, IP Intelligence, and other service-specific APIs
• Created from: The service page in the dashboard (e.g., DNS > Activate)

Personal Access Token (PAT)

Cross-service access with granular scopes. Used for the CLI, account management, and any workflow that spans multiple services.

• Format: wayscloud_pat_{10-char prefix}_{56-char secret}
• Example: wayscloud_pat_abc1234567_aBcDeFgHiJkLmNoPqRsTuVwXyZ...
• Use for: CLI, account management, databases, domain verification, multi-service automation
• Created from: Dashboard > Security > Personal Access Tokens

S3 Access Key

For S3-compatible storage access using AWS Signature V4.

• Format: Standard AWS access key + secret key pair
• Use for: Object Storage via boto3, AWS CLI, or any S3 client
• Created from: Dashboard > Storage > Bucket > Keys

---

Create a key

Service API Key (dashboard)

1. Navigate to the service you want to use (e.g., DNS, LLM, Verify)
2. Click Activate or API Keys
3. Copy the key immediately — it is only shown once

Personal Access Token (dashboard)

1. Go to Security in the sidebar
2. Click Personal Access Tokens > Create Token
3. Enter a name and select the scopes you need
4. Copy the token immediately — it is only shown once

From the API

curl -X POST https://api.wayscloud.services/v1/account/api-keys/pat \
  -H "Authorization: Bearer YOUR_EXISTING_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "scopes": ["vps:read", "vps:write", "dns:read"]
  }'

---

Use a key

Pass your key in the request header:

# X-API-Key header (service keys)
curl https://api.wayscloud.services/v1/dns/zones \
  -H "X-API-Key: wayscloud_dns_abc123_yoursecretkey"

# Bearer token (service keys or PATs)
curl https://api.wayscloud.services/v1/dns/zones \
  -H "Authorization: Bearer wayscloud_dns_abc123_yoursecretkey"

Both header formats work for all key types.

---

PAT scopes

Personal Access Tokens use granular scopes that control exactly what the token can do. Each scope follows the {service}:{action} format.

Scope reference

Group	Scope	Description
Account	account:read	View account profile and settings
	account:write	Modify account profile and settings
API Keys	api_keys:read	View API keys
	api_keys:write	Create and revoke API keys
SSH Keys	ssh_keys:read	View SSH keys
	ssh_keys:write	Create and delete SSH keys
Billing	billing:read	View billing and invoices
Services	services:read	View active services
VPS	vps:read	View servers, plans, templates, metrics
	vps:write	Create, start, stop, reboot, delete servers
DNS	dns:read	View zones, records, DNSSEC status
	dns:write	Create, modify, delete zones and records
Object Storage	storage:read	View buckets, credentials, quota
	storage:write	Create and delete buckets
Databases	database:read	List databases and view credentials
	database:write	Create and delete databases
	database:firewall	Manage database firewall rules
App Platform	app:read	View apps, logs, metrics, plans
	app:write	Create, start, stop, delete apps
	app:deploy	Deploy images and stacks
Redis	redis:read	View instances, credentials, plans
	redis:write	Create and delete instances
Contacts	contacts:read	View contacts and groups
	contacts:write	Create and manage contacts
Domain Verification	domain_verification:read	View domain verifications
	domain_verification:write	Create and manage verifications
Insight	workspace:read	View projects, documents, results
	workspace:write	Upload documents, create sources
	workspace:ingest	Ingest documents via API
CloudShell	shell:connect	Connect to interactive CloudShell

Scope hierarchy

Write scopes automatically include read access:

• vps:write implies vps:read
• dns:write implies dns:read
• database:write implies database:read
• database:firewall implies database:read
• app:deploy implies app:read (but not app:write)
• All other :write scopes imply their :read counterpart

This means a token with vps:write can both list and manage servers without explicitly adding vps:read.

Note: app:deploy and app:write are separate — deploy lets you push images but not delete apps, and write lets you manage apps but not deploy.

---

Key storage and security

• Keys are hashed (SHA-256) before storage — the plaintext is never stored in the database
• The full key is shown only once at creation, then only the prefix is visible
• Key secrets are stored encrypted in HashiCorp Vault for recovery during the same session
• Credentials files (CLI) are created with chmod 600

How keys are resolved

When a request arrives, the system:

1. Extracts the key from the Authorization or X-API-Key header
2. Identifies the key type from the prefix (wayscloud_pat_ vs wayscloud_{service}_)
3. Hashes the secret portion (SHA-256)
4. Looks up the hash in the database
5. Validates the key is active, not expired, and has the required scopes

---

Rotate a key

1. Go to the service page or Security > Personal Access Tokens
2. Click Regenerate or Rotate
3. Copy the new key immediately
4. Update your application

The old key stops working immediately after rotation.

Revoke a key

1. Go to the service page or Security
2. Click Revoke or Delete
3. Confirm the action

Revoked keys cannot be recovered. Create a new one if needed.

---

Best practices

• Copy once — Keys are shown only at creation. Store them in environment variables or a secret manager.
• One key per application — Don't share keys across apps. This makes rotation and revocation targeted.
• Minimum scopes — PATs should have only the scopes the application actually needs.
• Rotate regularly — Rotate keys on a schedule or when team members change.
• Never commit keys — Keep keys out of source control. Use .env files, CI/CD secrets, or Vault.

---

Related

• Authentication — header formats and auth methods
• Security — encryption, audit logging, and secret management
• WAYSCloud CLI — PAT-based CLI access
• Getting Started — create your first key