Authentication

All WAYSCloud API requests must be authenticated using API keys. This guide explains how authentication works, the different types of API keys, and best practices for keeping your keys secure.

Authentication Methods

WAYSCloud uses Bearer token authentication with API keys. Every API request must include your API key in the Authorization header.

Bearer Token Format

Authorization: Bearer wayscloud_{service}_{id}_{secret}

Components:

wayscloud_ - Prefix identifying WAYSCloud keys
{service} - Service type (storage, llm, database, dns, gpu)
{id} - Unique key identifier
{secret} - Secret key for authentication

Example Request

curl -X GET "https://api.wayscloud.services/v1/storage/" \
  -H "Authorization: Bearer wayscloud_storage_abc123_XyZ789SecretKey"

API Key Types

WAYSCloud offers different API key types based on the services you need to access.

Storage API Keys

Access S3-compatible object storage for files, backups, and static assets.

Format: wayscloud_storage_{id}_{secret}

Permissions:

Upload objects (PUT)
Download objects (GET)
Delete objects (DELETE)
List buckets and objects (GET)
Get object metadata (HEAD)

Example:

curl -X PUT "https://api.wayscloud.services/v1/storage/my-bucket/file.txt" \
  -H "Authorization: Bearer wayscloud_storage_abc123_YourSecretKey" \
  --data-binary @file.txt

LLM API Keys

Access large language models for AI-powered applications.

Format: wayscloud_llm_{id}_{secret}

Permissions:

Chat completions (POST /v1/chat/completions)
List models (GET /v1/models)
Streaming responses

Supported Models:

mixtral-8x7b
qwen3-80b-instruct
qwen3-80b-thinking
deepseek-v3
deepseek-r1
llama-3.1-405b

Example:

curl -X POST "https://api.wayscloud.services/v1/chat/completions" \
  -H "Authorization: Bearer wayscloud_llm_xyz789_YourSecretKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mixtral-8x7b",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Database API Keys

Manage PostgreSQL and MariaDB databases programmatically.

Format: wayscloud_database_{id}_{secret}

Permissions:

Create databases (POST)
Delete databases (DELETE)
List databases (GET)
Get credentials (GET)
Manage snapshots (POST, GET, DELETE)
Configure backups (PUT)
Manage firewall rules (POST, DELETE)

Example:

curl -X POST "https://api.wayscloud.services/v1/databases" \
  -H "Authorization: Bearer wayscloud_database_def456_YourSecretKey" \
  -H "Content-Type: application/json" \
  -d '{
    "db_type": "postgresql",
    "db_name": "my_app_db"
  }'

DNS API Keys

Manage DNS records for your domains.

Format: wayscloud_dns_{id}_{secret}

Permissions:

Create/update/delete DNS records
List zones and records
Manage DNSSEC

GPU API Keys

Access GPU-accelerated services for video generation, text-to-speech, and transcription.

Format: wayscloud_gpu_{id}_{secret}

Permissions:

Create GPU jobs
Check job status
Download results

Creating API Keys

Via Dashboard (Recommended)

Log in to my.wayscloud.services
Navigate to API Keys in the sidebar
Click Create New API Key
Select service(s):
- ☑️ Storage
- ☑️ LLM
- ☑️ Database
- ☑️ DNS
- ☑️ GPU
Enter a descriptive name
Click Create
Copy the API key immediately - it won't be shown again!

Important

API keys are shown only once during creation. Store them securely in a password manager or secrets management system.

Via API (Programmatic)

You can also create API keys programmatically using your Keycloak token:

curl -X POST "https://provision.wayscloud.net/api/v1/dashboard/api-keys" \
  -H "Authorization: Bearer {keycloak_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "service": "storage",
    "description": "API key for production storage access"
  }'

Security Best Practices

✅ Do's

Store keys securely
- Use environment variables (export WAYSCLOUD_API_KEY="...")
- Use secrets management (HashiCorp Vault, AWS Secrets Manager)
- Use password managers for personal keys
Rotate keys regularly
- Create new keys every 90 days
- Delete old keys after rotation
- Use different keys for different environments
Use least privilege
- Create separate keys for each service
- Use different keys for dev/staging/production
- Revoke keys when no longer needed
Monitor usage
- Check API usage regularly in the dashboard
- Set up billing alerts
- Review access logs

❌ Don'ts

Never commit keys to version control

# Bad - API key in code
api_key = "wayscloud_storage_abc123_Secret"

# Good - API key from environment
api_key = os.getenv('WAYSCLOUD_API_KEY')

Never share keys
- Don't send keys via email or chat
- Don't share keys across teams
- Create separate keys for each user/application

Never hardcode keys

// Bad - hardcoded API key
const apiKey = 'wayscloud_llm_xyz789_Secret';

// Good - from environment
const apiKey = process.env.WAYSCLOUD_API_KEY;

Never log keys
- Sanitize logs to remove API keys
- Don't include keys in error messages
- Be careful with debug output

Using API Keys in Code

Python

import os
import requests

# Load from environment variable
API_KEY = os.getenv('WAYSCLOUD_API_KEY')
if not API_KEY:
    raise ValueError("WAYSCLOUD_API_KEY environment variable not set")

# Make authenticated request
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.wayscloud.services/v1/storage/',
    headers=headers
)

print(response.json())

JavaScript (Node.js)

const axios = require('axios');

// Load from environment variable
const API_KEY = process.env.WAYSCLOUD_API_KEY;
if (!API_KEY) {
  throw new Error('WAYSCLOUD_API_KEY environment variable not set');
}

// Make authenticated request
const response = await axios.get(
  'https://api.wayscloud.services/v1/storage/',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

PHP

<?php
// Load from environment variable
$apiKey = getenv('WAYSCLOUD_API_KEY');
if (!$apiKey) {
    throw new Exception('WAYSCLOUD_API_KEY environment variable not set');
}

// Make authenticated request
$ch = curl_init('https://api.wayscloud.services/v1/storage/');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Go

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("WAYSCLOUD_API_KEY")
    if apiKey == "" {
        panic("WAYSCLOUD_API_KEY environment variable not set")
    }

    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.wayscloud.services/v1/storage/", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Printf("Status: %d\n", resp.StatusCode)
}

Environment Variables

Set up environment variables for different environments:

Linux/macOS

# Add to ~/.bashrc or ~/.zshrc
export WAYSCLOUD_API_KEY="wayscloud_storage_abc123_YourSecretKey"

# Or use .env file with python-dotenv
echo 'WAYSCLOUD_API_KEY=wayscloud_storage_abc123_YourSecretKey' > .env

Windows (PowerShell)

# Set for current session
$env:WAYSCLOUD_API_KEY = "wayscloud_storage_abc123_YourSecretKey"

# Set permanently
[System.Environment]::SetEnvironmentVariable(
    'WAYSCLOUD_API_KEY',
    'wayscloud_storage_abc123_YourSecretKey',
    'User'
)

Docker

# Dockerfile
ENV WAYSCLOUD_API_KEY=${WAYSCLOUD_API_KEY}

# docker run
docker run -e WAYSCLOUD_API_KEY="wayscloud_storage_abc123_YourSecretKey" myapp

# docker-compose.yml
services:
  app:
    environment:
      - WAYSCLOUD_API_KEY=${WAYSCLOUD_API_KEY}

Managing API Keys

Listing Keys

View all your API keys in the dashboard:

Go to my.wayscloud.services/api-keys
See all active keys with:
- Name and description
- Service permissions
- Creation date
- Last used date

Revoking Keys

If a key is compromised or no longer needed:

Go to API Keys in the dashboard
Find the key to revoke
Click Revoke or Delete
Confirm the action

warning

Revoking a key is immediate and cannot be undone. All applications using that key will stop working.

Key Rotation

Best practice: Rotate keys every 90 days

Create a new API key with the same permissions
Update your applications to use the new key
Test thoroughly in staging
Deploy to production
Delete the old key after 7 days (grace period)

Authentication Errors

401 Unauthorized

{
  "error": "Invalid or expired API key",
  "code": "AUTH_FAILED"
}

Causes:

API key is incorrect
API key has been revoked
Missing Bearer prefix
Extra spaces in header

Solution:

# Check your key format
echo "Authorization: Bearer wayscloud_storage_abc123_YourSecretKey"

# Verify in dashboard that key is active

403 Forbidden

{
  "error": "API key does not have permission for this service",
  "code": "INSUFFICIENT_PERMISSIONS"
}

Causes:

Using storage key for LLM API
Using LLM key for database operations
Key doesn't have required permissions

Solution: Create a new API key with correct service permissions.

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Causes:

Exceeded rate limit (1000 req/min for storage/LLM, 500 req/min for database)

Solution: Implement exponential backoff and retry logic.

API Key Scopes

Each API key has specific scopes based on the services selected:

Service	Scope	Endpoints
Storage	`storage:read`	GET, HEAD
Storage	`storage:write`	PUT, POST
Storage	`storage:delete`	DELETE
LLM	`llm:inference`	POST /v1/chat/completions
LLM	`llm:models`	GET /v1/models
Database	`database:manage`	All database endpoints
DNS	`dns:manage`	All DNS endpoints
GPU	`gpu:use`	All GPU endpoints

Next Steps

Creating API Keys - Detailed guide on creating keys
First API Call - Make your first authenticated request
Troubleshooting Authentication - Common auth issues and solutions

Support

Having authentication issues? Contact us:

Email: support@wayscloud.no
Documentation: docs.wayscloud.services
Dashboard: my.wayscloud.services

Authentication Methods​

Bearer Token Format​

Example Request​

API Key Types​

Storage API Keys​

LLM API Keys​

Database API Keys​

DNS API Keys​

GPU API Keys​

Creating API Keys​

Via Dashboard (Recommended)​

Via API (Programmatic)​

Security Best Practices​

✅ Do's​

❌ Don'ts​

Using API Keys in Code​

Python​

JavaScript (Node.js)​

PHP​

Go​

Environment Variables​

Linux/macOS​

Windows (PowerShell)​

Docker​

Managing API Keys​

Listing Keys​

Revoking Keys​

Key Rotation​

Authentication Errors​

401 Unauthorized​

403 Forbidden​

429 Too Many Requests​

API Key Scopes​

Next Steps​

Support​

Authentication Methods

Bearer Token Format

Example Request

API Key Types

Storage API Keys

LLM API Keys

Database API Keys

DNS API Keys

GPU API Keys

Creating API Keys

Via Dashboard (Recommended)

Via API (Programmatic)

Security Best Practices

✅ Do's

❌ Don'ts

Using API Keys in Code

Python

JavaScript (Node.js)

PHP

Go

Environment Variables

Linux/macOS

Windows (PowerShell)

Docker

Managing API Keys

Listing Keys

Revoking Keys

Key Rotation

Authentication Errors

401 Unauthorized

403 Forbidden

429 Too Many Requests

API Key Scopes

Next Steps

Support