Authentication

Every request to the WAYSCloud API must be authenticated. The method you use depends on what you are building.

Quick reference

Method	Best for	Header
Service API Key	Single-service integrations (DNS, LLM, Verify)	X-API-Key: wayscloud_dns_...
Personal Access Token	CLI, multi-service automation, account management	Authorization: Bearer wayscloud_pat_...
S3 Signature	Object Storage (boto3, AWS CLI)	AWS Signature V4
JWT Session	Dashboard and browser-based access	Automatic (cookie-based)

---

Service API Keys

Service API Keys authenticate requests to a single WAYSCloud service. Each key is scoped to one service (DNS, LLM, Verify, Storage, etc.) and cannot access other services.

Format: wayscloud_{service}_{10-char prefix}_{56-char secret}

How to use:

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

# Bearer token (also works)
curl https://api.wayscloud.services/v1/dns/zones \
  -H "Authorization: Bearer wayscloud_dns_abc1234567_yourSecretKey"

How to get one:

1. Open the service in the dashboard (e.g., DNS, LLM, Verify)
2. Click Activate or API Keys
3. Copy the key — it is shown only once

What it can access:

Only the service it was created for. A DNS key cannot access the LLM API, and an LLM key cannot manage DNS zones. This limits the blast radius if a key is compromised.

---

Personal Access Tokens

Personal Access Tokens (PATs) provide cross-service access with granular scope control. Use them for the CLI, CI/CD pipelines, Terraform, or any workflow that touches multiple services.

Format: wayscloud_pat_{10-char prefix}_{56-char secret}

How to use:

curl https://api.wayscloud.services/v1/vps \
  -H "Authorization: Bearer wayscloud_pat_abc1234567_yourSecretToken"

How to get one:

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

Scopes control access:

A PAT only works for the scopes you grant it. For example, a token with vps:read and dns:read can list servers and DNS zones but cannot create or delete anything.

Write scopes automatically include read: vps:write implies vps:read.

See API Keys for the complete scope reference.

CLI usage:

cloud login --token wayscloud_pat_abc1234567_yourSecretToken
cloud vps list
cloud shell connect

The CLI stores the token in ~/.wayscloud/credentials (chmod 600). You can also set WAYSCLOUD_TOKEN as an environment variable.

---

S3 Authentication

Object Storage uses AWS Signature V4, the same authentication mechanism used by Amazon S3. This means any S3-compatible tool or SDK works out of the box.

Credentials: Access key + secret key pair, generated per bucket.

How to use with boto3:

import boto3

s3 = boto3.client("s3",
    endpoint_url="https://storage.wayscloud.services",
    aws_access_key_id="wayscloud_s3_mybucket_abc123",
    aws_secret_access_key="your-secret-key"
)

s3.list_objects_v2(Bucket="my-bucket")

How to use with AWS CLI:

export AWS_ACCESS_KEY_ID="wayscloud_s3_mybucket_abc123"
export AWS_SECRET_ACCESS_KEY="your-secret-key"

aws s3 ls s3://my-bucket/ \
  --endpoint-url https://storage.wayscloud.services

How to get credentials:

S3 credentials are generated automatically when you create a bucket. Additional keys can be created from the bucket detail page or via API.

See Store Files for a complete walkthrough.

---

Dashboard sessions

The WAYSCloud dashboard uses OAuth 2.0 with Keycloak for browser-based authentication. This is automatic — you do not need to manage JWT tokens manually.

How it works:

1. You log in at my.wayscloud.services via Keycloak
2. A JWT access token is stored in an httpOnly cookie
3. All dashboard API calls include this token automatically
4. The token is refreshed transparently when it expires

CloudShell authentication:

When you open CloudShell in the console (Cmd+K), the dashboard generates a short-lived JWT (90 seconds) from your session. This token authenticates the WebSocket connection. You do not need to enter credentials.

When to care about this:

You don't, unless you are building a custom frontend that integrates with the WAYSCloud API. In that case, contact support for OAuth client credentials.

---

How the system validates keys

When a request arrives:

1. The API gateway extracts the token from Authorization: Bearer or X-API-Key
2. The key prefix identifies the type (wayscloud_pat_ = PAT, wayscloud_{service}_ = service key)
3. The secret is hashed with SHA-256
4. The hash is looked up in the api_keys table
5. The key must be active and not expired
6. For PATs: the required scope is checked against the token's granted scopes
7. For service keys: the service must match the endpoint being called

If any step fails, the API returns 401 Unauthorized (invalid key) or 403 Forbidden (valid key but insufficient permissions).

---

Error responses

Status	Meaning	Common cause
401	Invalid or missing credentials	Expired key, typo in key, missing header
403	Valid credentials but insufficient permissions	Missing scope, wrong service key, IP restriction
422	Valid auth but invalid request	Missing required fields, validation error

All error responses follow a consistent format:

{
  "detail": "Invalid API key",
  "status_code": 401
}

Error messages never include internal IPs, hostnames, or stack traces.

---

Choosing the right method

Building a single-service integration? Use a Service API Key. It is the simplest option and limits exposure to one service.

Building automation across multiple services? Use a Personal Access Token with only the scopes you need.

Using the WAYSCloud CLI? Use a PAT. The CLI stores it locally and uses it for all commands.

Accessing Object Storage from code or tools? Use S3 credentials with boto3, AWS CLI, or any S3-compatible SDK.

Using Terraform? Use a PAT for resources that require it (databases, domain verification) and a Service API Key for service-specific resources (DNS, VPS).

---

Related

• API Keys — create, manage, and rotate keys; full scope reference
• Security — encryption, Vault, audit logging
• WAYSCloud CLI — PAT-based command-line access
• Getting Started — your first API call